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Preface 


This manual is the third in a series about processing lists 
with PL/I. It assumes knowledge of the two preceding man- 
uals, Introduction to the List Processing Facilities of PL/I 
(GF20-0015) and Techniques for Processing Data Lists in 
PL/I (GF20-0018). 

This manual builds upon the preceding manuals to 
extend the concept of processing simple and complex data 
lists to include techniques for processing pointer lists and 
lists of lists. Function and subroutine procedures used to 
manipulate the lists are illustrated. Use of suitable inline 
coding may be preferred for applications. 

The illustrative programs compiled and executed. Rea- 


Note: 


this manual. 


Version 5 of the PL/I (F) Compiler under control 
of the IBM System/360 Operating System (Release 
18.6) produced the program printouts shown in 


sonable care has been exercised to minimize error. Clarity 
of presentation has been emphasized rather than efficient 
programming or computer utilization techniques. 

The advanced nature of this manual requires the reader 
to be an experienced programmer who has studied the 
companion texts mentioned above and who is skilled in the 
use of subroutines and functions. References to particular 
implementations of PL/I are held to a minimum, but in- 
formation on the F-level facilities for processing lists 
appears in IBM System/360: PL/I Reference Manual 
(GC28-8201) and JBM System/360 Operating System: PL/I 
(F) Programmer’s Guide (GC28-6594). 
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Introduction 


This introduction defines the organization of data lists, 
pointer lists, and lists of lists. Diagrammatic representation 
of the three types of list organization is shown. This manual 
illustrates techniques for processing pointer lists and lists of 
lists. 


DATA LISTS 


A data list is made up of allocations of based variable struc- 
tures containing data plus pointer elements that link the 
structures:. 


DECLARE 

1 DATA_LIST_COMPONENT BASED(P), 

2 DATA CHARACTER (80), 

2 LINK POINTER, 

(P, SAVE, HEAD_ POINTER) POINTER: 
ALLOCATE DATA _LIST_ COMPONENT SET(P): 
HEAD POINTER, SAVE =P; 

ALLOCATE DATA LIST COMPONENT SET(P); 
SAVE->LINK = P; 

SAVE =P: 

ALLOCATE DATE_LIST_COMPONENT SET(P): 
SAVE->LINK = P; : 

P->LINK = NULL; 


The data list organization resulting from such code is repre- 
sented in Figure I.1. 


{| HEAD_POINTER DATA | LINK 


Figure I.1. Data list organization 


A data list has two significant limitations: (1) all data 
items in the list generally must have the same attributes, 
and (2) the same data item cannot be shared by two or 
more lists at the same time; a distinct copy of the item 
must appear in each list, thereby reducing conservation of 
storage. 


POINTER LISTS 


The cited limitations of data lists can be avoided by replac- 
ing the data items in list components with pointer variables 


that specify the locations of data items outside the list. 
Such a pointer list component can be specified as follows: 


DECLARE 
1 POINTER LIST COMPONENT BASED(P), 
2 DATA_PTR POINTER, 
2 PTR_ LINK POINTER, 
(P_HEAD, P) POINTER, 
DATA CHARACTER(80); 


Linked allocations of the type of list component associated 
with such a declaration are represented in Figure I.2. Such 
lists are called pointer lists because they consist of linked 
pointers. They retain the advantages of list organization 
while allowing the same data item to be shared (pointed to) 
by different lists and permitting the data items associated 
with a list to have different attributes. 


P_HEAD DATA_PTR}|PTR_LINK 


DATA_PTR}PTR_LINK DATA_PTR NULL 


Figure 1.2, Pointer list 


It is possible to allow a data list to contain data items 
with different attributes. However, such a list must be proc- 
essed on an individual basis. Pointer lists, on the other 
hand, permit general rather than specific processing tech- 
niques to be developed for all lists and still allow the data 
items associated with a list to possess a variety of attributes. 

Chapter 1 of this manual discusses pointer lists. 


LISTS OF LISTS 


The flexibility of a pointer list can be extended to organize 
lists in higher-level lists called lists of lists. Each component _ 
in a list of lists can contain three elements: | 

1. A pointer variable that specifies the location of the 
next component in the list 


2. Another pointer variable that specifies the location of 
the data item or the sublist associated with the component 

3. A type code that indicates whether a data item (code 
‘D’) or a sublist (code ‘L’) is associated with the com- 
ponent. | 


The elements can be specified as follows: 


DECLARE | | 
1 LIST OF LISTS COMPONENT BASED(P), 
2 CODE CHARACTER(1), _ 
2 SUB_PTR POINTER, 
2 LIST LINK POINTER, 


_ (L_HEAD, P) POINTER, 
DATA CHARACTER(80); 


Linked allocations of this type of list component are 
represented in Figure 1.3. _ . 
Each sublist can contain other sublists to an arbitrary 
depth, and the number of components permitted in each 
sublist is also arbitrary. This type of organization retains 
the advantages of pointer lists and also frees the program- 
mer from having to know the exact number of lists that will 
be required during a particular run of a program. New lists 
can be accommodated by treating them as sublists within a 
master list. 
Chapter 2 of this manual discusses lists of lists. 


L_HEAD | rae SUB_ PTR] LIST_LINK COE SUB_PTR | NULL 


DATA 


or SUB_PTR | LIST_LINK E00 SUB_PTR | NULL 


Figure I.3. List of lists 


jaa | DATA 


Chapter 1. Pointer Lists 


An essential characteristic of a data list is that its data items 
appear within the body of the list. As a result, a data item 
must be duplicated if it is to be a member of two different 
data lists. Duplication of a small data item, such as a single 
character, does not require much storage. However, duplica- 
tion of a large data item, such as a long string, or an array 
or structure with many elements, may lead to excessive use 
of storage. 

A way of avoiding duplicate storage is to store the 
address of a data item rather than the data item itself in a 
list. Then storage need be allocated for only one copy of 
the item. 

The type of list produced by this arrangement is called a 
pointer list to distinguish it from a data list. This chapter 
shows how pointer lists may be organized and how they 
permit more efficient use of computer storage and program 
execution time. 


ORGANIZING POINTER LISTS 


Figure 1.1 illustrates the organization of a pointer list. Each 
list component contains two pointer elements: DATA and 
LINK. The DATA pointer contains the address of the data 
item associated with the component. LINK points to the 
next list component. 


Separating Storage for Data Items and 
List Components 


The data items associated with a pointer list can be of any 
storage class and data type and can be located anywhere 
within a program. They can even be intermixed with their 
associated list components in the same storage area. A less 
complicated arrangement would involve separate areas for 
list components and data items. Figure 1.2 shows how a 


Component Declaration Example of Pointer List 


1 COMPONENT BASED(P), 


2 DATA POINTER, 
2 LINK POINTER; 


Figure 1.1. L’xample of a pointer list 


1 MAIN_AREA, 
2 LIST_AREA AREA(5000), 


2 DATA_AREA AREA(20000), 








Figure 1.2. Subdividing an area for list storage and data storage 


structure organization can be used to divide an area into 
separate list storage and separate data storage. 


Sharing Data Items Among Pointer Lists 


The illustration in Figure 1.3 shows how two data lists (L1 
and L2) may share data items. Both lists contain the same 
first two data items, but storage is required for only one 
copy of each item. 





Figure 1.3. Two pointer lists with data items in common 


The same data item may appear on an arbitrary number 
of pointer lists and may also appear an arbitrary number of 
times on the same list. 


Observe that the fourth component of L1 contains a null 


data pointer, which allows a data item to be removed from 
a pointer list without requiring a corresponding deletion of 
the component. This use of a null data pointer avoids the 
need to link the list component to the list of available stor- 
age components when it is known that the list will use the 
component again. 

Also note that the size of L1 is five, even though its 
fourth position contains a null data pointer. As a result, a 
null data item is considered to be a possible member of a 
pointer list. 

Because the illustrations for pointer lists can become 
complicated, a more compact representation is often desir- 
able. Figure 1.4 contains an abbreviated representation of 
pointer lists. 





2 ChE bEDPEN 


Figure 1.4. Abbreviated representation of pointer lists 


Storing Mixed Data Types in Pointer Lists 


The techniques used for organizing data lists in Techniques 
for Processing Data Lists in PL/I (GF20-0018) do not per- 
mit data lists to contain mixed data types. Such flexibility 
would require continual allocating and freeing of compo- 
nent storage on an individual basis and would eliminate the 
efficiency obtained from a list of available storage compo- 
nents. | 

With pointer lists, however, mixed data types are pos- 
sible without a loss in efficient storage handling. Figure 1.5 
shows a pointer list that contains four data items. The first 
element in each item represents a type code that distin- 
guishes the item. The first item is a four-position array; the 
second, a single character; the third, a three-element struc- 
ture; and the fourth, a single character. A type code would 
not be necessary if the items always appeared in a predeter- 
mined pattern. 


Me ol 





Figure 1.5; A pointer list with data items of mixed type; the first 
element of each item serves as a type code 


Since data items do not appear within the body of a 
pointer list, the components of the list can have the same 
structure. It is possible, therefore, to create a list of avail- 
able storage components for pointer lists that contain data 
items of mixed type. . 

Deletion of a data item from a pointer list can return the 
associated list component to the list of available storage 
components without destroying the data item. The data 
item can still be a member of another list, as illustrated in 
Figure 1.6. | 





B. After deletion of last item from L1 


uo CBEDRELPELPER 
2 2 TTP ELHELHER 


C. Abbreviated form after deletion 


Figure 1.6. Deletion of an item from a pointer list 


Freeing Data Storage 


A count can be attached to each data item to specify the 
number of lists that contain the item. As the item is insert- 
ed into or deleted from a list, the count can be adjusted 
appropriately. A zero count would indicate that the item 
belonged to no list and that its storage could be freed. 


PROCESSING POINTER LISTS 


The techniques for processing pointer lists resemble those 
for processing data lists, except that the addresses of data 
items and not the data items themselves are manipulated 
within pointer lists. Insertion, deletion, and retrieval of a 
data item associated with a pointer list always involve the 
address of the item. | 

This section presents elementary subroutines and func- 
tions (Figures 1.7 through 1.16) for processing simple 
pointer lists that possess the linear organization developed 


earlier in this chapter. Elementary procedures are developed 
first and used in turn to create higher-level procedures. 

Because of the similarity between the techniques of this 
chapter and those in Techniques for Processing Data Lists 
in PL/I, fewer procedures are developed here. The range of 
development is restricted to those procedures needed for 
the examples in the next section, “Using Pointer Lists’’. 
More extensive methods for processing pointer lists, includ- 
ing recursive techniques, appear in Chapter 2, which dis- 
cusses lists of lists. 


AREA_OPEN_P Subroutine 


Purpose 





To create a list of available storage components 
| Reference 
AREA _OPEN_P(P_AREA,P_LIST) 


Entry-Name Declaration 











DECLARE AREA_OPEN_P ENTRY(AREA\(*), 
| POINTER); 
Meaning of Arguments 


P AREA -— the area variable that is to contain the 
| list of available storage components 


P LIST | — the pointer variable that serves as the 
head of the list of available storage 


components | 
Cc 








Figure 1.7A. Description of the AREA OPEN P subroutine for 
creating a list of available storage compartments 


AREA_OPEN_P: 
PROCEDURE (P_AREA, P_LIST);3 
DECLARE 
P_AREA AREA(*), 
(P_LIST, T) POINTER, 
1 P_COMP BASED(P), 
2 DATA POINTER, 
2 LINK POINTER; 
ON AREA BEGIN; 
IF 
Pa=NULL 
THEN 
P->LINK = NULL; 
Go To 
END_AREA_OPEN_P; 
END; 
P = NULL; 
ALLOCATE P_COMP IN(P_AREA) 
SET(P); 


P_LLIST = P; 


T= Ps : 
ALLOCATE P_COMP IN(P_AREA) 
SET(P)$ 
‘T=>LINK = P3 

GO TO 


L; 
END_AREA_OPEN_P: 
END 

AREA_OPEN_P3; 


Figure 1.7B. The AREA OPEN P subroutine 


ADDRESS_N_P Function 
Purpose 


To obtain the address of the nth component ina 
pointer list 


Reference 
ADDRESS_N_P(P_LIST,N) 
Entry-Name Declaration 
DECLARE ADDRESS_N_P ENTRY (POINTER, 
FIXED DECIMAL(5)) 
~RETURNS(POINTER); 


Meaning of Arguments 


P_LIST |§— the pointer variable that is the head 
7 of the list to be examined © 
N. — a fixed-point decimal integer value 


that specifies the component whose 
address is to be obtained; N has a 
-maximum size of five digits 


Figure 1.8A. Description of the ADDRESS N_P function for 
obtaining the address of the nth component in a 
pointer list 


ADDRESS_N_P: 
PROCEDURE (P_LLIST, N) 
RETURNS (POINTER)$ 
DECLARE 
P_LIST POINTER, 
(NeI) FIXED DECIMAL(S), 
1 P_COMP BASED(ADDRESS), 
2 DATA POINTER, 
2 LINK POINTERS 
IF | 
(P_LIST = NULL) | (N < 1) 
THEN : 
RETURN (NULL); 
ADDRESS = P_LIST$ 


DO 
I = 1 BY 13 
IF ; | . 
(ADDRESS=>LINK = NULLIE (I-=N) 
THEN 
RETURN (NULL) 3 
IF 
I = N 
THEN 
RETURN( ADDRESS) $ 
ADORESS = ADDRESS->LINK 3 


ADDRESS_N_P$ 


Figure 1.8B. The ADDRESS _N_P function 


GET_LINK_P Function 


Purpose 


To obtain the address of the next component in a 
pointer list 


Reference 
GET_LINK_P(ADDRESS) | 
Entry-Name Declaration 


DECLARE GET_LINK_P ENTRY(POINTER) 
RETURNS(POINTER); 


Meaning of Argument 


ADDRESS — a pointer value that specifies the 


| address of a list component | 


Figure 1.9A. Description of the GET LINK _P function for 


obtaining the address of the next component ina | 


pointer list 


GET_LINK_Ps 
| PROCEDURE (ADDRESS) 
RETURNS (POINTER); 
DECLARE 
1 P_COMP BASED(ADDRESS), 
2 DATA POINTER, 
2 LINK POINTER; 
IF 
ADDRESS = NULL 
THEN 
RETURN (NULL) S$ 
RETURN(ADDRESS—>LINK)$ 
ENO | | 
GET_LINK_P;$ 


Figure 1.9B. The GET LINK P function 





| 
| 
| 
| 
| 


GET DATA_P Function 
Purpose 


To obtain the value of the data pointer ina 
component of a pointer list 


Reference 


GET_DATA_P(ADDRESS) 


Entry-Name Declaration 


DECLARE GET _DATA_P ENTRY (POINTER) 
RETURNS(POINTER); 


Meaning of Argument 


ADDRESS — a pointer value that specifies the 
address of a pointer list component 





Figure 1.10A. Description of the GET DATA _P function for 
obtaining the value of the data pointer in a 
component of a pointer list 


GET_DATA_P: 
PROCEDURE (ADDRESS) 
RETURNS (POINTER); 
DECLARE 
1 P_COMP BASED(ADDRESS), 
2 DATA POINTER, 
2 LINK POINTER; 
IF 
ADDRESS = NULL 
THEN 
RETURN (NULL) 
RETURN( ADDRESS->DATA) ; 
END 
GET_DATA_P; 


Figure 1.10B. The GET DATA_P function 





SET_LINK_P Subroutine 
Purpose 


To assign a value to the link pointer of a component 
in.a pointer list 


Reference 


SET_LINK_P(ADDRESS,L) 


Entry-Name Declaration; 


DECLARE SET_LINK_P ENTRY(POINTER, 
POINTER); 


Meaning of Arguments 


ADDRESS — a pointer value that specifies the 
address of a pointer list component 


— the value to be assigned to the link 
element of the list component 


Figure 1.11A. Description of the SET _LINK_P subroutine for 
assigning a value to the link pointer of a component 
in a pointer list 


SET_LINK_P: 
PROCEDURE (ADDRESS ,L)5 
DECLARE 
L POINTER, 
1 P_COMP BASEOCADDRESS), 
2 DATA POINTER, 
2 LINK POINTER; 
IF 
ADDRESS = NULL 
THEN 
RETURNS; 
ADDRESS->LINK = Ls; 
END 
SET_LINK_P3$ 
Figure 1.11B, The SET LINK _P subroutine 


| SET_DATA_P Subroutine 
Purpose 


To assign a value to the data pointer of a component 
in a pointer list 


Reference 
SET_DATA_P(ADDRESS, D) 
Entry-Name Declaration 


DECLARE SET_DATA_P ENTRY (POINTER, 
POINTER); | 


Meaning of Arguments 


ADDRESS — a pointer value that specifies the 
address of a list component 


D — the pointer value to be assigned to the 
data pointer of the list component 


Figure 1.12A. Description of the SET_DATA_P subroutine for 
assigning a value to the data pointer of a component 
in a pointer list | 


SET_DATA_P: 
PROCEDURE (ADDRESS ,D)3 
DECLARE 
| D POINTER, 
1 P_COMP BASEOD(ADORESS), 
2 DATA POINTER, 
2 LINK POINTER? 
IF 
ADORESS = NULL 
THEN | | 
RETURNS 
ADORESS->DATA = D3 
END . 
SET_DATA_P3 


Figure 1.12B. The SET_DATA_P subroutine 


SIZE_P Function 
Purpose 


To obtain the number of data pointers (null and 
non-null) in a pointer list aa 


Reference 
SIZE _P(P_LIST) 
Entry-Name Declaration 


DECLARE SIZE_P ENTRY(POINTER) 
RETURNS(FIXED 
DECIMAL (5)); | 


"Meaning of Argument 


P_ LIST | — the pointer variable that is the head 


of the list to be examined 


Figure 1.13A. Description of the SIZE_P function for obtaining: 
the number of data pointers in a pointer list 


SIZE_P: 
PROCEDURE (P_LIST) 
RETURNS (FIXED DECIMAL(5))5 
DECLARE 
(P_LISTe ADDRESS) PCINTER, 
N FIXED DECIMAL(5); 
ADDRESS = P_LIST; 


DO 
N = 0 BY ls 
_IF 
ADDRESS = NULL 
THEN _ 
RETURN(N) 5 
ADORESS = GET_LLINK_PCADDRESS) S$ 
END; 
END 


SIZE_P$ 


Figure 1.13B. The SIZE_P function 


INSERT _ND_P Subroutine 
Purpose 


To insert a data pointer into the nth position of a 
pointer list 


Reference 
INSERT_ND_P(P_LIST,N,D) 
Entry-Name Declaration 


DECLARE INSERT_ND_P ENTRY(POINTER, 
FIXED DECIMAL (5), POINTER): 


Meaning of Arguments 


P_LIST — the pointer variable that is the head of 
the list to be processed 


N — the position in the list where the data 
| pointer is to be inserted : 


D = the pointer value to be inserted 


Figure 1.14A. Description of the INSERT ND_P subroutine for 
inserting a data pointer into the nth position of a 
pointer list 


INSERT_NO_P: 
PROCEDURE(P_LISTs Ny» 013 
DECLARE 
N FIXED DECIMAL(5), 
(P,Q) POINTER, 
(P_LIST, Dy ADORESS1, ADDRESS2, 
AVAIL_P EXTERNAL) POINTER; 
/* IF LIST OF AVAILABLE STORAGE 
COMPONENTS IS EMPTY, THEN PRINT 
MESSAGE AND RETURN. */ 
IF AVAIL_P = NULL THEN 003 
PuT | 
LIST(*LIST OF AVAILABLE STORAGE IS 
EMPTY"); 
RETURN; END; 
/* ASSIGN DATA ITEM TO FIRST 
COMPONENT IN LIST OF AVAILABLE 
STORAGE. */ 
CALL SET_DATA_P(AVAIL_P, D)3 
/* IF P_LLIST IS NULL OR N€2_ INSERT 
FIRST COMPONENT OF AVAIL_P INTO 
FIRST POSITION OF LIST AND RETURN*/ 
IF 
(P_LLIST = NULL) | (N < 2) 
THEN DO; 
ADDRESS1 = P_LIST; P_LIST = AVAIL_P; 
AVAIL_P = ADDRESS_N_PC(AVAIL_Py 2)3 
CALL SET_LINK_P(P_LIST,ADDRESS1)3 
RETURN; END; 
IF N > SIZE_P(P_LIST) 
THEN DO; 


P = PLLISTS$ 

DO WHILE(P -~= NULL); 
Q = Ps P = Q=->LINKs 
END; 

Pe, Q—>LINK = AVAIL_PS 


AVAIL_P = ADDRESS_N_PCAVAIL_P, 2)35 
P—>LINK = NULLS; 

RETURN; 

END; 


/* OTHERWISE OBTAIN THE ADDRESS CF 
THE N-TH COMPONENT OF P_LLIST. ¥*/ 
ADDRESS2 = ADDRESS_N_P(P_LLIST, N); 
ADDRESS1 = ADDRESS_N_PCUPLLIST, N-1)5 
/* INSERT FIRST COMPONENT OF AVAIL_P 
INTO THE N-TH POSITION OF P_LLIST. */ 
CALL SET_LINK_P(ADDRESS1, AVAIL_P); 
ADORESS1 = AVAIL_Ps; 

AVAIL_P = ADDRESS_N_PCAVAIL_P,s 2)3 
CALL SET_LINK_P(CADDRESS1, ACORESS2)3 


END INSERT_ND_P$ 


Figure 1.14B. The INSERT _ND_P subroutine 


GET _ND_P Function 


To get the value of the data pointer in the nth 
position of a pointer list 


Reference 
GET _ND_P(P_LIST,N) 
Entry-Name Declaration 


DECLARE GET _ND_P ENTRY(POINTER, FIXED 


DECIMAL (5)) 
RETURNS(POINTER); 


Meaning of Arguments 


P LIST §— the pointer variable that is the head of 


the list to be processed 


— the position of the data pointer whose | 
value is to be obtained 


Figure 1.15A. Description of the GET _ND_P function for getting 


the value of the data pointer in the nth position of 
a pointer list 


GET_ND_P: | : | 
| PROCEDURE (P_LIST, N) 
| RETURNS (POINTER); 
DECLARE | 
P_LIST POINTER, 
N FIXED DECIMAL(5); 
RETURN(GET_DATA_P 
(ADDRESS_N_PCP_LIST, ND))3 
END 3 | 
GET_ND_P; 


Figure 1.15B. The GET_ND_P function 


DELETE ND _P Subroutine 
Purpose 


To delete the data pointer in the nth position of a 
pointer list 


Reference 
DELETE ND_P(P_LIST,N) 
Entry-Name Declaration 
DECLARE DELETE _ND_PENTRY(POINTER, 
FIXED 
DECIMAL (5)); 


Meaning of Arguments 


P LIST | — the pointer variable that is the head of 
the list to be processed 
N — the position of the data pointer to be 


deleted 


Figure 1.16A. Description of the DELETE ND _P subroutine for 
deleting the data pointer in the nth position of a 
pointer list | 


DELETE_ND_P: 
PROCEDURE (P_LIST, N)3 
DECLARE | 
N FIXED DECIMAL(5), 
(P_LIST»ADDRESS1,ADORESS2,ADDRESS3, 
AVAIL_P EXTERNAL) POINTERS 
/* IF PLLIST. IS EMPTY OR N IS LESS 
THAN 1, THEN RETURN. */ 
IF | 
(P_LLIST = NULL) | (N < 1) 
THEN 
RETURN; 
/* DELETE FIRST COMPONENT IF N 
EQUALS l. */ | 
IF | 
N= 1 
THEN 


10 


DO; 3 | 
ADDRESS2 = P_LIST$ 
P_LESTF = ADDRESS_N_POP_LIST, 2)3 
GO TO . 
L; 
END$ 
/* OBTAIN N-TH COMPONENT. */ 
ADDRESS2 = ADDRESS_N_PC(P_LIST.ND3 
IF 
ADDORESS2 = NULL 
THEN 
RETURNS | 
AODRESS1 = ADORESS_N_P(P_LIST,N-1)3 
ADDRESS3 = AODRESS_N_PCP_LEIST Nel) s 
/* DELETE N-TH COMPONENT. */ 
CALL SET_LINK_P(ADORESS1,AOORESS3)3$ 
/* INSERT DELETED COMPONENT INTO 
LIST OF AVAILABLE STORAGE 
COMPONENTS. */ 
Ls 
ADORESS1 = AVAIL_P$ 
AVAIL_P = ADDRESS23 
CALL SET_LINK_PCAVAIL_P,ADDORESSI)S 
END 


DELETE_NO_P; 


Figure 1.16B. The DELETE ND _P subroutine 


USING POINTER LISTS 


Pointer lists possess the same advantages as data lists in 
providing efficient control over varying storage require- 
ments. As with data lists, pointer lists need not reserve 
dormant storage in anticipation of maximum requirements; 
storage not needed by one list can be used by another. 

Pointer lists also provide two additional benefits not 
obtained from data lists. They permit a data item to bea 
member of two or more lists at the same time and also 
eliminate unnecessary data movement. Both benefits are 
obtained by manipulating the addresses of data items rather 
than the items themselves. 

The following discussions demonstrate these advantages 
by two examples. The first example shows how multiple 
sorts may be performed efficiently on the records of a file 
by manipulating the addresses of the records. The second 
example illustrates how different arrangements of the same 
records on separate pointer lists permit efficient searching 
of the records for different key values. | 


Multiple Sorting of Records 


Figure 1.17 presents the M_SORT program, which shows 
how a sort can be made more efficient by avoiding unneces- 
sary data movement. The program obtains records from the ~ 
standard system-input file (SYSIN) and prints the records 
in two different sorted arrangements on the standard 
system-output file (SYSPRINT). 


M_SORT: 
PROCEDURE ; 
DECLARE 
(I eJeSIZELZSIZE2) 
FIXED DECIMAL(5), 
(AVAIL_P EXTERNAL, AUTHOR_LIST, 
TITLE_LISTs Ply P2) POINTER, 
1 MAIN_AREA, 
LIST_AREA AREA, 
DATA_AREA AREA, 
CARD, 
FIELOl CHARACTER(15), 
FIELO2 CHARACTER(25), 
FIELO3 CHARACTER(10), 
FIELD4 CHARACTER( 30), 
DOCUMENT BASED(P1), 
AUTHOR CHARACTER(15), 
TITLE CHARACTER( 25), 
SUBJECT CHARACTER(10), 
DESCRIPTORS CHARACTER(30)35 
/* WHEN DATA_AREA IS EXHAUSTED OR 
ALL DOCUMENT CARDS HAVE BEEN READ, 
GO TO PRINT_AUTHOR_LIST. */ 
ON AREA 
GO TO | 
PRINT_AUTHOR_LIST3 
ON ENDFILE (SYSIN) 
GO TO 
PRINT_AUTHOR_LIST3$ 
7* INITIALIZE. */ 
SIZE1L,SIZE2 = 03 
AUTHOR_LIST,TITLE_LIST = NULL; 
/* FORM LIST OF AVAILABLE STORAGE 
COMPONENTS IN LIST_AREA. ¥*/ 
CALL AREA_OPEN_P(LIST_AREA,AVAIL_P)$ 
/* GET DOCUMENT CARDS, AND ASSIGN 
THEM TO STORAGE ALLOCATED IN 
DATA_AREA. ALSO FORM A POINTER 
LIST OF DOCUMENT CARDS SORTED ON 
AUTHOR. */ 
#AUTHOR =: 
OO WHILE 
(1B); 
/* DO WHILE(1B) IS TERMINATED */ 
/* BY EOF OR AREA CONDITION */ 
GET 
EDIT(CARD)(A(15) A025) 2A(10),A(30))5 
ALLOCATE DOCUMENT IN(DATA_AREA) 
SETC(P1)$ 
P1->DOCUMENT = CARD; 
/* FIND INSERTION POINT IN 
AUTHOR_LIST. */ 


NM AN RN AY & —\ AN 


DO 
I = 1 TO SIZEl BY 1; 
P2 = GET_ND_P(AUTHOR_LISToI)35 
IF P2 = NULL 
THEN GO TO INSERT_AUTHOR3; 
IF } 
P1->AUTHOR<P2—->AUTHOR 
THEN 
GO TO 
INSERT_AUTHOR $ 
END; 


/* INSERT ADDRESS OF DOCUMENT IN 
AUTHOR_LIST. */ 


INSERT_AUTHOR: 
CALL INSERT_ND_P(AUTHOR_LIST,IyP1)35 


Figure 1.17. The M_SORT procedure 


x 


SIZE1 = SIZE1+135 
END_AUTHOR: 
END 
#AUTHOR S$ 
/* PRINT AUTHOR_LIST. ¥*/ 
PRINT_AUTHOR_LIST: 
PUT 
PAGES 
PUT 
LISTC*AUTHOR FILE"); 
PUT 
SKIP(2) 35 
DO 
I = 1 TO SIZE1 BY 1; 
Pl = GET_ND_P(CAUTHOR_LIST,I); 
PUT 
EDI T(P1-—>DOCUMENT) (A); 
PUT 
SKIPs5 
END; , 
/* SORT DOCUMENT CARDS ON TITLE. */ 
#TITLE: 
DO 
J = 1 TO SIZE1 BY 13 
/* GET AND DELETE ADDRESS OF FIRST 
DOCUMENT FROM AUTHOR_LIST. */ 
Pl = GET_ND_P(AUTHOR_LIST,1)35 
CALL DELETE_ND_P(AUTHOR_LIST,1)3 
/* FIND INSERTION POINT IN 
TITLE_LIST. */ 
DO 
I = 1 TO SIZE2 BY 13 
P2 = GET_ND_P(TITLE_LIST,I)5 
IF P2 = NULL 
THEN GO TO INSERT_TITLE$ 
IF 
P1->TITLE<P2->TITLE 
THEN 
GO TO 
INSERT_TITLEs 
END; ; 
/* INSERT ADDRESS OF DOCUMENT IN 
TITLE_LIST. */ 
INSERT_TITLE®? 
CALL INSERT_ND_P(TITLE_LIST, I,P1)5 
SIZE2 = SIZE2 + 135 
END_TITLE: 
END 
#TITLEs 
/* PRINT TITLE_LIST. */ 
PRINT_TITLE_LIST:= 
PUT 
PAGEs 
PUT 
LISTC*TITLE FILE')$ 
PUT 
SKIP(C2)3 
DO 
I = 1 TO SIZE1 BY. 13 
Pl = GET_ND_P(TITLE_LIST,1)3 
PUT | 
EDIT(P1->DOCUMENT) (A); 
PUT 
SKIP s$ 
ENO; 
END 
M_SORTS | 
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Each record describes a document and contains four 
fields: AUTHOR, TITLE, SUBJECT, and DESCRIPTORS. 
_ The records are printed in sort order: first on AUTHOR, 
then on TITLE. — oe 
As document cards are read, storage is allocated in 
DATA_AREA, and the address of each card is stored in the 


pointer lists AUTHOR_ LIST, which is arranged in ascending | 


sequence on AUTHOR. LIST AREA contains all list com- 
- ponents. 

After AUTHOR _LIST is used to print the document 
cards in sort order, successive data addresses are removed 
from the list and inserted into the pointer list TITLE _ 
LIST, which is arranged in ascending sequence on TITLE. 
This list is used in the second printing of the sorted docu- 
ment cards. 

Note that during both sorts the document cards remain 
at their original storage locations within DATA AREA; 
only the addresses of the cards are rearranged within both 
lists. As a result, less data is moved, and a more efficient 
sort is obtained. 

When the number of document cards exceeds the storage 
capacity of DATA AREA, only those cards that can be 
stored in the area are sorted. 


Multiple Searching of Records 


Since the same data item may be referred to simultaneously 
by two different pointer lists, it is possible to maintain 
more than one sort arrangement of a single set of data 
items. Multiple arrangements of this type avoid data dupli- 
cation and permit faster searching of items on different 
keys. | 

Figure 1.18A contains the SEARCH program, which 
arranges a set of records on two different keys and searches 
the records for specified values of the keys. Each record 
describes a document and contains four fields: AUTHOR, 
TITLE, SUBJECT, and DESCRIPTORS. The records are 
read from the standard system-input file (SYSIN) and 
stored at locations allocated within DATA_AREA. The 
addresses of the records are stored in two pointer lists: 
AUTHOR _LIST and TITLE_LIST. AUTHOR _LIST is 
arranged in ascending sequence on AUTHOR and TITLE _ 
LIST, on TITLE (as shown in Figure 1.18B). LIST AREA 
provides all storage for list components. 


SEARCH: 
PROCEDURE ; 

DECLARE 
1 MAIN_AREA, 
2 LIST_AREA AREA, 
2 DATA_AREA AREA, 
(AVAIL_P EXTERNAL, AUTHOR_LIST, 
TITLE_LIST, Pl, P2) POINTER, 
(SIZE, I) FIXED DECIMAL(5), 
SEARCH_CARD CHARACTER(80), 
TITLE_ITEM CHARACTER(25), 
AUTHOR_ITEM CHARACTER(15}y 

1 CARD, 
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FIELD] CHARACTER(15), 
FIELD2 CHARACTER(25)y 
FIELD3. CHARACTER(10), 
FIELD4 CHARACTER(30)_. 
DOCUMENT BASED(P1), 
AUTHOR CHARACTER(15)> 
TITLE CHARACTER(25)9 
SUBJECT CHARACTER(10)» 
DESCRIPTORS CHARACTER(30)3 | 
/* WHEN DATA AREA CANNOT HOLD ALL 
DOCUMENT CARDS, OR ALL SEARCH 7 
CARDS HAVE BEEN PROCESSED, TERMINATE 
PROGRAM. *¥/ | 
ON AREA 
GO TO 
END_SEARCH; 
ON ENOFILE (SYSIN) 
GO TO 
‘END_SEARCH3 
/* INITIALIZE. */ 
SIZE = 03 | 
AUTHOR_LIST, TITLE_LIST = NULL3 
/* FORM LIST OF AVAILABLE STORAGE 
COMPONENTS IN LIST_AREA. */ 
CALL AREA_OPEN_P(LIST_AREA,AVAIL_P)3 
/* GET DOCUMENT CARDS, AND ASSIGN 
THEM TO STORAGE ALLOCATED IN 
DATA_AREA. ALSO FORM SORTED AUTHOR 
LIST AND TITLE LIST. #/ 
GET_DOCUMENT_CARD: 
~ GET 


N PR MR A —& NM A A AY 


EDIT(CARD)(A(15), A(25)5 A(10), 

A(30))3 3 
IF . 

SUBSTR(FIELDL, 1, 5) = *hueege 

THEN 

GO TO 

DOCUMENT_SEARCH3 
ALLOCATE DOCUMENT IN(DATA_AREA) 
SET(P1)3 
P1->DOCUMENT. = CARD; 
4* FIND INSERTION POINT IN AUTHOR 


LIST. ¥*/ 
DO | 
I = 1 TO SIZE BY 13 
P2 = GET_ND_P(AUTHOR_LIST, I)5 
IF P2 = NULL 
THEN GO TO INSERT_AUTHOR; 
IF 
P1->AUTHOR<P2—>AUTHOR. 
THEN 
GO TO 
INSERT_AUTHOR$ 
END$ 


4* INSERT ADDRESS OF DOCUMENT IN 
SORTED AUTHOR LIST. #7. 
INSERT_AUTHOR: 

CALL INSERT_NO_P(AUTHOR_LIST,I,P1)3 
/* FIND INSERTION POINT IN TITLE 


LIST. */ 
DO 
I = 1 TO SIZE BY 13 
P2 = GET_ND_P(TITLE_ LIST» I); 
IF P2 = NULL 
THEN GO TO INSERT_TITLES 
IF 
! P1->TITLE<P2->TITLE 
THEN 
GO TO 
INSERT_TITLE$ 
END; 


/* INSERT ADDRESS OF DOCUMENT IN 
SORTED TITLE LIST. ¥*/ | 


INSERT_TITLE: a 
CALL INSERT_ND_P(TITLE_LISTy1,P1)3 
/* INCREASE SIZE BY ONE, AND GET 
NEXT DOCUMENT CARD. */ 
SIZE = SIZE + 13 


GET_DOCUMENT_CARD$ 
/* READ SUCCESSIVE SEARCH CARDS, 
AND PRINT CORRESPONDING DOCUMENT 
CARDS. */ 
DOCUMENT_SEARCH: 

GET 
EDI T(SEARCH_CARD) (A(80))5 

PUT 
SKIP(2)3 

PUT 
EDIT (SEARCH_CARD) (A(80))5 

IF 

SUBSTR(SEARCH_CARD, ly 1) = ‘A® 


AUTHOR_SEARCH; 
/* PERFORM TITLE SEARCH. */ 
TITLE_SEARCH:? 
TITLE_ITEM = SUBSTR(SEARCH_CARD, 
2, 25)3 
DO 

I = 1 TO SIZE BY 13 

Pl = GET_ND_P(TITLE_LIST, 1); 
IF 

TITLE_ITEM<P1—>TITLE 

THEN 
GO TO 

DOCUMENT_SEARCH3 
IF 

TITLE_ITEM = P1->TITLE 


AUTHOR_LIST: 


~*~ AUTHOR TITLE SUBJECT DESCRIPTORS 


SORTING BUSINESS 






ROEAS SORTING 


METHODS 


AMES RS GENERAL 









Ea | 
INI LADD E K BASIC 


COMPUTING 








/ AUTHOR | TITLE SUBJECT DESCRIPTORS 





STATISTICS 


AUTHOR | TITLE SUBJECT DESCRIPTORS 


PROGRAMMING; PROGRAMMING 





THEN 
PUT 
EDIT(P1->DOCUMENT ) 
(COLUMN(1),A015),A025),A010),A(30))5 
END; | 
/* WHEN THIS POINT IS REACHED, GET 
NEXT SEARCH CARO. */ 
GO TO 
DOCUMENT_SEARCH3$ 
/* PERFORM AUTHOR SEARCH. */ 
AUTHOR_SEARCH3: 
AUTHOR_ITEM = SUBSTR(SEARCH_CARD, 
22 15)3 
DO 
I = 1 TO SIZE BY 13 
Pl = GET_NO_P(AUTHOR_LIST, I)3. 
IF 
AUTHOR_ITEM<P1->AUTHOR 
THEN 
GO TO 
DOCUMENT_SEARCH3; 
IF a 
AUTHOR_ITEM = P1->AUTHOR 
THEN 
PUT 
ENIT(P1->DOCUMENT ) 
(COLUMN(1),A015) ,A025),A(10),A(30)93 
END; | 
/* WHEN THIS POINT IS REACHED, GET 
NEXT SEARCH CARD. */ 
GO TO 
DOCUMENT_ SEARCH? 
ENO_SEARCHS: 
ENO | 
SEARCH; 


Figure 1.18A. The SEARCH procedure 


TITLE _ LIST: 


SORTING 





8/19/62 





MATHEMATICS 
STATISTICS 
1957 












COMPUTERS 
1960 


Figure 1.18B. How single copies of document cards are arranged in sort order on two different pointer lists 
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A trailer card with asterisks in cc 1 through 5 follows the 
last document card in the input file. If DATA AREA 
cannot hold all the document cards, the program is 
terminated. 

The remaining input cards are search dards. which con-. 
tain two items: a type code and a key value. The type code 
appears in cc 1 and must be either the letter A or the letter 
T. Type code A indicates that the key value is the name of 
an author, which appears left-adjusted in cc 2 through 16 of 
the search card. The key value associated with type code T 
is a title, which appears left-adjusted in cc 2 through 26. 

- As each search card is read, the appropriate pointer list, 
either AUTHOR_ LIST or TITLE_LIST, is searched for the 
specified AUTHOR value or TITLE value. All document 
cards that contain the key value are printed along with 
the search card on the standard aaa a file 
(SYSPRINT). 

Associating the document cards with two sorted pointer 
lists eliminates the need for exhaustive searching through all 
the document cards. Each search ends when the specified 
- key exceeds the key value in the current document card. 

The SEARCH program need not be restricted to two 
pointer lists; a pointer list can be created for each field in 
the document cards. In a more elaborate. program a pointer 
list can be created for each key value. For example, a: 
pointer list can be created for all document cards that con- 
tain the SUBJECT value “programming”. With such a list, 
no searching is required, since the list contains only those 
document cards that have “programming” as their SUB- 
JECT value. The term “inverted file” is often used to 
describe such arrangements. 


LIST_AREA 








NO 


AVAIL: 


L1: 


DATA_AREA 


Figure 1.19. Pointer lists 
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REVIEW OF POINTER LISTS 


This chapter shows how to overcome the main disadvan- 


tages of data lists by replacing each data item in a list with a 
pointer variable that specifies the address of the data item 


outside the body of the list (see Figure 1.19). The resulting 


pointer list still retains flexible control over varying storage 
requirements, but it also eliminates much of the duplication 
and movement of data produced by data lists and allows. 
mixed data types to be associated with the same list. 


SUMMARY 


1. Pointer lists resemble data lists, except that the 
address of a data item rather than the data item itself 
appears in a pointer list. | 

2. Pointer lists provide the same advantages as data lists 
in maintaining efficient control over varying storage re- 
quirements. Pointer lists also possess the following addi- 
tional benefits: 

a. A data item may be shared by two or more pointer 

lists, thus avoiding data duplication. 

b. Transmission of data addresses (rather than data 
items) to and from pointer lists reduces data move- 
ment. 

c. Different orderings of the same collection of data 
items may be obtained with separate pointer lists. 

d. Mixed data types may be associated with the same 
pointer lists. 
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Chapter 2. Lists of Lists 


The previous chapter shows how pointer lists may be used 
to link various combinations of data elements, arrays, and 
structures. However, pointer lists need not be restricted to 
these types of items; the lists themselves can also appear as 
members of a pointer list. The higher-level list formed by 
this type of linkage is called a list of lists. This chapter 
describes how such lists are constructed and shows how 
they extend the general flexibility and efficiency of pointer 
lists. 


ORGANIZING LISTS OF LISTS 


A pointer list and a list of lists use pointer values to link 
data items that appear outside the body of the list. Since a 
list of lists can link other lists as well as data items, some 
method must be used to determine whether a list com- 
ponent specifies a data item or a sublist. 

The following discussions use a type code within each 
list component to distinguish between a data item and a 
sublist, and illustrate the effect of this code upon list organ- 
ization and list-processing techniques. 


Component Elements for Lists of Lists 


Each component in a list of lists may contain three ele- 
ments: 

1. A type code (TYPE), which is a single-position 
character string that contains the character ‘D’ (for data 
item) or the character ‘L’ (for list) 

2. A value pointer (VALUE), which specifies the 
address of a data item or a sublist 

3. A link pointer (LINK), which specifies the address of 
the next component in the list 


The declaration in A of Figure 2.1 shows how these 
elements may be combined to form a list component 
(COMPONENT). 

A schematic representation of a component for a 
list of lists appears in B of Figure 2.1. 

The diagram in C of Figure 2.1 shows a list com- 
ponent that specifies a data item (the character *). 

In D of Figure 2.1, the component with type code 
‘L’ specifies a sublist. The first component in the sub- 
list specifies a data item (the character *). 

Note that the VALUE pointer in a list component 
with type code ‘L’ serves as the head pointer of the 
specified sublist. 





DECLARE TYPE VALUE LINK 
14 COMPONENT BASED(P), 

2 TYPE CHARACTER(1), 

2 VALUE POINTER, 


2 LINK POINTER; 


B. List component 


A. Component Declaration 


C. List component that refers D. List component that 


to a data item refers to a sublist 


Figure 2.1. Hlustrations of list components for lists of lists 


Permissible Arrangements of List Components 


A list of lists can contain D-components only, L-compo- 
nents only, or any combination of D- and L-components. 
The number of levels to which sublists may be linked is 
arbitrary and limited only by available storage. 

Figure 2.2 shows a list of lists that contains data items 
only. Part A displays the full form of the list; storage areas 
for the data items are shown outside the body of the list. A 
more compact representation appears in Part B which 
shows the data items within the body of the list. Since it is 


A. Full form 


uo (PED EETHPER 


B. Compact form 





Figure 2.2. A list of lists that contains data items only 
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A. Full form 






B. Compact form 


Figure 2.3. A list of lists that contains lists at the top level only 
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A. Full form 


B. Compact form 





Figure 2.4. A list of lists that contains both data items and lists at the top level . 


understood that the value element in a list component 
always contains the address of a data item and not the item 
itself, the two representations in Figure 2.2 may be con- 
sidered equivalent. | 

The use of single-character data items in Figure 2.2 is 
arbitrary; a list of lists can contain data items of any size 
and type. 

Figure 2.3 shows how three sublists may be linked to 
form a higher level list. The linking is done so that the 
resulting lists of lists contains the sublists at the top level. 

A combination of data items and lists at the top level of 
a list of lists appears in Figure 2.4, and Figure 2.5 presents a 
list of lists that contains data items and lists at multiple 
levels. 


me: | Peed | 
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Null Lists of Lists 


As with data lists and pointer lists, a null address value for 
the head pointer of a list of lists creates a null list (A in 
Figure 2.6). Note the distinction between a list of lists with 
a null head and a list of lists that contains a null data item 
(B in Figure 2.6). A list with a null head has zero size, but a 
list of lists that contains a null data item requires a list 
component for the item and, therefore, has a size of one. 

Observe further the difference between a list of lists that 
contains a null data item (B in Figure 2.6) and a list of lists 
that contains a null list (C in Figure 2.6). Both lists have a 
size of one, but the first contains a D-component, and the 
second, an L-component. 
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A. Full form 
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B. Compact form 
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Figure 2.5. A list of lists that contains data items and lists at multiple levels 
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A. A null list of lists 


Ls: |_| 1D INN 


B. A null data item in a fist of lists 


L6: | HL ININ 


C. Anull list in a list of lists 





_ Figure 2.6. Examples of null lists of lists 


For the purposes of this book, the three lists of lists in 
Figure 2.6 are considered to be null lists because they con- 
tain null value pointers. As a result, a null list of lists can — 
have a size greater than zero. Such a size represents the 
number of components in the null list. 


Sharing Data Items Among Lists of Lists 


The ability of two or more pointer lists to share the same 
data item is retained by lists of lists. Figure 2.7 shows how 
two lists of lists can contain the same data items without 
requiring duplicate storage for the items. Although the 
compact forms of both lists may seem to indicate dupli- 
cation of the data items, remember that the value element 
of a list component contains the address of an item and not 
the item itself. 

Sharing of data items among lists of lists permits direct 
access to various subsets of items in a collection. The list of 
lists L_ARRAY in Figure 2.8, for example, contains eight 

sublists-ELEMENTS, ROW1, ROW2, COL1, COL2, 
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DIAG1, and DIAG2—which contain various combinations 
of the elements in a two-dimensional array. Although each 
element of the array appears in four sublists, storage for _ 
only one copy of each element is required. | 

A similar application of lists of lists may be used to 
represent the organization of PL/I structures. As an 
example, consider the list of lists L_ STRUCTURE in 
Figure 2.9. This list contains three sublists, which represent 
the three minor structures declared at the left of the dia- 
gram. 


B. Compact form 





Figure 2.7. Sharing data items among lists of lists 


DECLARE ARRAY (2,2) 
CHARACTER(1) INITIAL(‘A’,’B’,'1','2’); 


L_array: [_| DOR. Onn. OBN 


ELEMENTS: 


Figure 2.8. A list of lists that contains various sets of elements from the same array 
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DECLARE | | L_ STRUCTURE: . To... U: 

1 STRUCTURE, ed ——»|D}+} belole|\ 
2 A, . 
3 T CHARACTER(1) INITIAL(‘+'), - A: 

CHARACTER(1) INITIAL(‘6’), 


V: | W: xX: 
CHARACTER(1) INITIAL (‘2’), D{2] befo] | Pepls\\ 


Cc 


CHARACTER(1) INITIAL(’.’), 
CHARACTER(1) INITIAL(‘8’), 


xs< 


= 


CHARACTER(1) INITIAL(‘—’), 


| OMe Z: 
CHARACTER(1) INITIAL (‘4’); iD }—| | BLN 


WW OO WWW DW Ww 


N < 





Figure 2.9. A list of lists that represents a PL/I data structure 


Sharing List Components Among Lists of Lists 


Not only may data items be shared among lists of lists, but 
list components may be shared as well. Figure 2.10 shows 
how the components for items X and Y are shared between 
lists LO and L10. 

This type of sharing eliminates unnecessary duplication 
of list components as well as data items. Note that the 
L-component in Figure 2.10 could also be shared between 
L9 and L10. The organization in Figure 2.10, however, 
permits the L-component to be deleted from either list 
without affecting the other list. | 





A. Full form 


Parenthetic Representation of Lists of Lists 


A shorter method of showing the organization of a list 
appears in Figure 2.11, which contains a parenthetic repre- 
sentation of a list of lists. The parenthetic representation 
contains a sequence of items separated by commas. Paren- 
these enclose the sequence, and a colon attaches the name 
of the list to the left parenthesis. 

The list presented in Figure 2.11 contains no sublists. 
Should sublists appear in the list, they are also enclosed in B. Compact form 
parentheses, as shown in Figure 2.12. Additional levels of 
sublists are represented by further nesting of parentheses. 





Figure 2.10. Sharing list components among lists of lists 
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The circularities displayed in Figure 2.13 and 2.14 are 
formed by linking successive list components by means of 
link pointers. Value pointers can also be used, however, to 
form circular lists of lists, as shown in Figure 2.15. This 
type of linkage produces a nested circularity, because the 
sublist involved links back to a component at a higher level 
L11: (X.Y,Z) in the list of lists. 

Cycling three times through the diagram in Figure 2.15 
generates the following list: 

LIS(X(Y,Z(X(Y,Z,(X(Y,Z)))) 
Such lists are useful in modeling data organizations that 
Figure 2.11. Compact and parenthctic representations of a list of have a recursive structure. 


lists without sublists 


uv (hPL PEPLPEER 


A. Compact form 


B. Parenthetic form 





L13: eELeEYL ELH 


A. Compact form 


A. Compact form 
L13: (X,Y,Z,X,Y,Z[,X,Y,Z] ...) 


B. Parenthetic form 


L12: (X,(Y,2Z)) 





B. Parenthetic form 7 7 
Figure 2.13. A circular list of lists without sublists 





Figure 2.12. Compact and parenthetic representations of a list of 


lists with a sublist 


Circular Lists of Lists 


The parenthetic representation of lists is particularly useful 
in displaying the organization of circular lists. Figure 2.13 
contains the parenthetic representation of a circular list of 
lists that does not contain sublists. An ellipsis (... ) indi- L14: (XAY.Z).XAYZLXAY.Z J 
cates the endless cycling of the list, and square brackets 
({ ]) enclose the items that are repeated each cycle. 

The parenthetic representation of a circular list of lists 
that contains a sublist appears in Figure 2.14. Note that 
square brackets do not denote a sublist but determine the 
scope of the ellipsis. 


A. Compact form 


B. Parenthetic form 





Figure 2.14. A circular list of lists with a sublist 
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A. Compact form 


L15: (XAY,Z(X(Y,Z,(1X(Y,Z,(]) .. 0) 


B. Parenthetic form 





Figure 2.15. A list of lists with a nested circular sublist 


PROCESSING LISTS OF LISTS 


The following discussions develop subroutines and func- 
tions for processing lists of lists. The organization of these 
procedures resembles the organization used in Chapter 1: 
elementary procedures are developed first and used in turn 
to create higher-level procedures. | 

The procedures are not designed to process lists that 
contain circularities. Such lists would place many of the 
procedures—particularly recursive procedures—into endless 
loops. Circular lists are handled more conveniently on an 
individual basis. | 

This section organizes the procedures into four cate- 
gories: 

1. Creating a list of available storage components 

2. Manipulating component elements in a list of lists 

3. Manipulating the top level of a list of lists 

4. Manipulating all levels of a list of lists 
No attempt is made to develop an exhaustive collection of 
procedures; instead, the emphasis is on general methods. 

Many of the techniques used in this section have been 
influenced by the list-processing language LISP, which is in 
an interpretive programming language developed at the 
Massachusetts Institute of Technology.* 


Creating a List of Available Storage Components 


Figure 2.16A, 2.16B, and 2.16C present the AREA OPEN 


subroutine for creating a list of available storage components. 


The subroutine requires two arguments: 


*Berkeley, Edmund C., and Bobrow, D. G. (editors) The Pro- 
gramming Language LISP: Its Operation and Applications. 
Cambridge, Massachusetts: The M.I.T. Press, 1966 (2nd printing) . 


ZZ 


| 1. An area variable throughout which list components 
are to be allocated | 
2. A pointer variable that serves as the head of the list of 


available dlOraRe components 


The area argument passed to AREA OPEN can be of 
any storage class and is not restricted to a particular size, 
but storage for the area must have been allocated before the 
subroutine is invoked. | 

The AREA _OPEN procedure can be used to establish a 
list of available storage components named LIST. The com- 
ponents can be organized into a list of lists specifying data 
items. Another invocation of AREA OPEN can establish a 
list of available storage components named AVAIL. These 
latter components relate to insertion and deletion of list 
components in the list named LIST. The following code is 
pertinent: 


DECLARE 
(AREA1, AREA2) AREA, 
(LIST, AVAIL EXTERNAL) POINTER; 
CALL AREA_OPEN(AREA1, LIST); 
CALL AREA _OPEN(AREA2, AVAIL); 


A list component deleted from the list named LIST can 
be inserted into the list named AVAIL. Conversely, a list 
component can be deleted from the list named AVAIL as 
needed for insertion into the list named LIST. 

This subroutine resembles the similarly named procedure © 
in Chapter 1, except that it creates a list of available storage 
components for lists of lists. 


AREA_OPEN Subroutine 
Purpose 
To create a list of available storage components 
Reference 
AREA_OPEN(AREA, LIST) 
Entry-Name Declaration 


DECLARE AREA_OPEN ENTRY(AREA\(*), 
POINTER); 


Meaning of Arguments 


AREA — the area variable that is to contain the 
list of available storage components 
LIST — the pointer variable that serves as the 
head of the list of available storage 
components 
Remarks 


Storage must have been allocated for the AREA 
argument before AREA_OPEN is invoked. 


The LIST argument is assumed to be null upon 
entry to AREA_OPEN. 


Other Programmer-Defined Procedures Required 
None — 
Method 


Storage for list components is allocated with the 
following based structure: 


1 COMPONENT BASED/(P), 

2 TYPE CHARACTER (1), 

2 VALUE POINTER, 

2 LINK POINTER, 
Components are allocated throughout AREA until the 
AREA ON-condition occurs. The LIST argument 
contains the address of the first component. The LINK 
element of each component contains the address of the 


next component. The LINK element of the last 
component has a null value. 


Figure 2.16A. Description of the AREA OPEN subroutine for creating a list of available storage components 


AREA_OPEN: 
PROCEDURE (AREA, 
DECLARE 
P POINTER, 
AREA AREA(*), 
(LIST, T) POINTER, 
1 COMPONENT BASED(P), 
2 TYPE CHARACTER(1), 
2 VALUE POINTER, 
2 LINK POINTER; 


LIST); 


/* WHEN ALL STORAGE HAS BEEN 
ALLOCATED IN AREA, SET LINK PCINTER 
OF LAST COMPONENT, IF ANY, TO NULL 
AND RETURN. ¥*/ 
ON AREA 
BEGINS 
IF 
P-rm=NULL 
THEN 
P=->LINK = NULL; 
GO TO 
END_AREA_OPEN; 


Figure 2.16B. The AREA OPEN subroutine 


END; 
/* ALLOCATE FIRST COMPONENT IN 
AREA, AND ASSIGN COMPONENT 
ADDRESS TO POINTER PARAMETER CALLED 
LIST. */ 
P = NULL; 
ALLOCATE COMPONENT IN(AREA) 
SET(P)3 
LIST = P3 
/* CONTINUE ALLOCATING COMPONENTS IN 
AREA UNTIL ALL STORAGE HAS BEEN 
ALLOCATED. LINK EACH COMPONENT TG 
THE PREVIOUSLY ALLOCATED 
COMPONENT. */ 

L: 
T = P; 
ALLOCATE COMPONENT IN( AREA) 
SET(P)3 | 
T—->LINK = P3 

GO TO 

L3 

END_AREA_OPEN: 

END 
AREA_OPEN; 
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Subroutine | | oe Result | ; 
Reference | . 


AREA_OPEN(STORAGE_AREA,AVAIL) 












STORAGE AREA 
COCR CCRC 
~TORHOO 








Figure 2.16C. An example of a reference to the AREA _ OPEN subroutine 


Manipulating Component Elements in a List of Lists 


_ The following discussions develop subroutines and 
functions for: | 
1. Obtaining the address of a list component 
2. Obtaining the values of elements in list components 
3. Assigning values to the elements of list components 
4. Comparing the data values of list components 


These procedures eliminate the syntactic details associated 
with PL/I pointer qualification and allow the programmer 
to view and process lists of lists in a more application- 
oriented manner. 


Obtaining the Address of a List Component 


The following discussions develop two function procedures 
for obtaining the address of a specified list component: 
1. ADDRESS _NVT, which obtains the address of the 
component that contains the nth value at the top level of a 
list of lists 
2. ADDRESS_LVT, which obtains the address of the 
component that contains the last value at the top level of a 
list of lists ! 


Later discussions show how to obtain the address of a 
component that is not at the top level of a list. 
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ADDRESS_NVT Function 
Figures 2.17A, 2.17B, and 2.17C present the ADDRESS _ 
NVT function procedure. This function requires two 


arguments: 
1. A pointer variable that forms the head of the list 


being processed 


ADDRESS_NVT Function 


Purpose 


To obtain the address of the nth component at the 
top level of a list of lists 


Reference 
ADDRESS_NVT(LIST, N) 
Entry-Name Declaration 
DECLARE ADDRESS _NVT ENTRY(POINTER, 


FIXED DECIMAL (5)) 
RETURNS(POINTER); 


Meaning of Arguments 


LIST — the pointer variable that is the head of 
the list to be examined 


2. An integer that indicates the sequential position 


(first, second, third, etc.) of a value at the top level of the 
list 


The function returns the address of the component that 
contains the specified value. 


N — a fixed-point decimal integer value 
that specifies the component whose 
address is to be obtained; N has a 
maximum size of five digits 


Remarks 
A null pointer value is returned when LIST is null, 
N is less than one, or N is greater than the number 
of components at the top level of LIST. 

Other Programmer-Defined Procedures Required 
None 

Method 
The function proceeds through the top level of 
LIST until the (n-1)th component is reached. The 


link pointer of this component contains the address 
of the nth component. 


Figure 2.17A. Description of the ADDRESS NVT function for obtaining the address of the nth component at the top level of a list of lists 


ADDRESS_NVT: 
PROCEDURE (LIST»N) 
RETURNS (POINTER) $ 
DECLARE 
LIST POINTER, 
(NeI) FIXED DECIMAL(5), 
1 COMPONENT BASEDCADORESS)» 
2 TYPE CHARACTER(1), 
2 VALUE POINTER, 
2 LINK POINTERS 
IF 
(LIST = NULLITCNCKL) 
THEN 
RETURN (NULL)$ 
ADORESS = LIST; 


Figure 2.17B. The ADDRESS_NVT function 


00 
I= 1 BY 13 
IF 
(ADDRESS->LINK = NULL) & (I-=N) 
THEN 
3 RETURN (NULL)3$ 
IF | 
I =N 
THEN | 
RETURN(AODRESS)$ 
ADDRESS = ADDRESS->LINK; 
END; 
END 


ADORESS_NVT3 
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Function 


: Reference 


ADDRESS_NVT(L1,1) 


ADDRESS_NVT(L1,2) - 


ADDRESS_NVT(L1,3) 





Function 


Value 


Address of component that 
specifies W 


Address of component that 
specifies the sublist contain- 
ing X and Y 


Address of component that 
specifies Z 


Figure 2.17C. Examples of references to the ADDRESS _ NVT 


function 


ADDRESS_LVT Function 

Many list-processing operations involve the last value at the 
top level of a list of lists. It is convenient, therefore, to have 
a function that specifically obtains the address of the last 
component at the top level. 


ADDRESS_LVT Function 
Purpose 


To obtain the address of the last component at the 
top level of a list of lists 


Reference 


ADDRESS_LVT(LIST) 


Entry-Name Declaration 


DECLARE ADDRESS_LVT ENTRY(POINTER) 


RETURNS(POINTER); 


Meaning of Argument 





Figures 2.18A, 2.18B, and 2.18C present the ADDRESS 
_LVT function procedure, which returns the address of the 
last component at the top level of a list. The function 
requires one argument: the pointer variable that forms the 
head of the list being processed. 


— the pointer variable that is the head of 
the list to be examined 


pemarke 
A null pointer value is returned when LIST is null. 
Other Programmer-Defined Procedures Required 
None 
Method 
The function proceeds through the top level of LIST 
until the last component is reached. The link 


pointer in the next-to-last component contains the 
address of the last component. | 


Figure 2.18A. Description of the ADDRESS _ LVT function for obtaining the address of the last component at the top level of a list of lists 
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ADDRESS_LVT: 
PROCEDURE(LIST) 
RETURNS (POINTER); 

DECLARE 

: ADDRESS POINTER, 

(LIST, SAVE, ADDRESS1) PCINTER, 

1 COMPONENT BASED(ACORESS), 

2 TYPE CHARACTER(1), 

2 VALUE POINTER, 

2 LINK POINTER; 

ADDRESS, ADDRESS1 = LIST; 


DO 

WHILE (CADDRESS1+=NULL) § 
SAVE = ADORESS13 
ADDRESS1 = ADDRESS->LINKA; 
ADDRESS = SAVE; 

END; 
RETURN( ADDRESS); 

END 


ADORESS_LVT; 


Figure 2.18B, The ADDRESS _LVT function 


Ea ii re rh tee 
Function Function 
Reference Value 


ADDRESS_LVT(L1) Address of component that 


specifies Z 
ADDRESS_LVT(L2) Address of component that 
specifies the sublist containing 
U and V 


Figure 2.18C. Examples of references to the ADDRESS _LVT 


function 





Obtaining the Values of Elements in List Components 


Many list-processing operations examine the values of the 
elements in list components. The following discussions 
develop three function procedures for obtaining these 
values: 

1. GET_ LINK, which obtains the value of the link 
pointer in a specified list component 

2. GET _VALUE, which obtains the value of the value 
pointer in a specified list component 

3. GET_TYPE, which obtains the value of the type 
code in a specified list component 


GET_LINK Function 

Figures 2.19A, 2.19B, and 2.19C present the GET _ LINK 
function, which uses the address of a list component as its 
argument. The function returns the value of the link 
pointer in the specified list component. The effect of this 
function is to obtain the address of the next list 
component. 


GET VALUE Function 

Figures 2.20A, 2.20B, and 2.20C present the GET VALUE 
function, which uses the address of a list component as its 
argument. The function returns the value of the value 
pointer in the specified list component. 


GET_TYPE Function 

Figures 2.21A, 2.21B, and 2.21C present the GET TYPE 
function, which uses the address of a list component as its 
argument. The function returns the value of the type code 
in the specified list component. 
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GET_LINK Function 


ADDRESS —a pointer value that specifies the _ 
Purpose ‘4 | | address of a component in a list of 
| lists 


To obtain the address of the next component at the 
top level of a list of lists | Remarks 


Reference The function assumes that ADDRESS represents a 
valid address of a component in a list of lists. If 
GET_LINK(ADDRESS) ADDRESS is null, a null pointer value is returned. 


Entry-Name Declaration Method 


DECLARE GET_LINK ENTRY(POINTER) _. The function returns the address contained in the 
| RETURNS(POINTER); link pointer of the component specified by 
ADDRESS. | 
Meaning of Argument 





Figure 2.19A. Description of the GET LINK function for obtaining the address of the next component at the top level of a list of lists 


GET_LINK: | 2 LINK POINTERS 

PROCEDURE (ADDRESS) | IF } 3 
| RETURNS (POINTER); ADDRESS = NULL 

DECLARE THEN 
ADDRESS POINTER, . RETURN (NULL)$ 
1 COMPONENT BASED(C ADDRESS), RETURN( ADDRESS—>LINK) 5 
2 TYPE CHARACTER(1), END 
2 VALUE POINTER, GET_LLINKS 


Figure 2.19B. The GET_LINK function 


Function Function 
. Reference Value 


GET_LINK(L1) Address of component that specifies the 
sublist containing X and Y 


GET_LINK(ADDRESS_NVT(L1,2)) Address of component that specifies Z 


GET_LINK(ADDRESS_LVT(L1)) Null address 


GET_LINK(NULL) Null address 





Figure 2.19C.. Examples of references to the GET_ LINK function 
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GET_VALUE Function 
Purpose 


To obtain the address of the value associated with a 
component in a list of lists 


Reference 
GET_VALUE(ADDRESS) 
Entry-Name Declaration 


DECLARE GET_VALUE ENTRY(POINTER) 
RETURNS(POINTER); 


Meaning of Argument 





ADDRESS — a pointer value that specifies the 
address of a component in a list of 
lists 


Remarks 


The function assumes that ADDRESS represents a 
valid address of a component in a list of lists. If 
ADDRESS is null, a null pointer value is returned. 


Other Programmer-Defined Procedures Required 
None 
Method 


The function returns the address value of the value 
pointer in the component specified by ADDRESS. 


Figure 2.20A. Description of the GET VALUE function for obtaining the address of the value associated with a component in a 


list of lists 


GET_VALUE: 
PROCEDURE (AODRESS) 
RETURNS (POINTER); 
DECLARE 
ADDRESS POINTER, 


1 COMPONENT BASED( ADDRESS)» 


2 TYPE CHARACTER(1), 
2 VALUE POINTER, 


Figure 2.20B. The GET VALUE function 


2 LINK POINTERS 
IF 
ADDRESS = NULL 
THEN 
RETURN (NULL); 
RETURN(ADDRESS->VALUE)$ 
END 
GET_VALUE $ 


Function Function 
Reference Value 
GET_VALUE(ADDRESS_LVT(L1)) Address of Z 


GET_VALUE(ADDRESS_NVT(L1,2)) 


GET_VALUE(ADDRESS_NVT( 


Address of sublist containing X and Y 


= Address of X 
GET_VALUE(ADDRESS_NVT(L1,2)),1) | 


GET_VALUE(NULL) 





Null address 


Figure 2.20C. Examples of references to the GET_ VALUE function 
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GET_TYPE Function 
Purpose 


To obtain the type code from a component in a list 
_ of lists 


Reference 
GET_TYPE(ADDRESS) 
Entry-Name Declaration 


DECLARE GET_TYPE ENTRY(POINTER) 
| RETURNS(CHARACTER 
(1)); 


Meaning of Argument 


GET_TYPE: 

PROCEDURE (ADORESS) 
RETURNS (CHARACTER(1))5 
DECLARE | 


ADDRESS POINTER, | 
1 COMPONENT BASED( ADDRESS), 
2 TYPE CHARACTER(1), 
2 VALUE POINTER, | 


Figure 2.21B. The GET TYPE function © 


ADDRESS — a pointer value that specifies the 
address of a component in a list of 
lists 


Remarks 


The function assumes that ADDRESS represents a 
valid address of a component in a list of lists. If 
ADDRESS is null, type code ‘D’ is returned. 

Other Programmer-Defined Procedures Required 
None 


Method 


The function returns the value of the type element 
in the specified component. The value is a single 
alphameric character. 


| Figure 2.21A. Description of the GET TYPE function for obtaining the type code from a component in a list of lists 


2 LINK POINTERS 
IF 
ADORESS = NULL 
THEN 
RETURN(*D*)5 
RETURN( ADDORESS->TYPE) 5 
END 7 
GET_TYPEs 


Function Function 
Reference Value 


GET_TYPE(ADDRESS_LVT(L1)) 


GET_TYPE(ADDRESS_NVT(L1,2)) 


GET_TYPE(ADDRESS_LVT( 


‘D’ (Type code for Z) 


‘L’ (Type code for sublist) 


‘D’ (Type code for Y) 


GET_VALUE(ADDRESS_NVT(L1,2)))) 


GET_TYPE(NULL) 





‘D’ (Type code for null item) 


Figure 2.21C. Examples of references to the GET_ TYPE function 


Assigning Values to Elements of List Components 


The link pointers and value pointers of list components 
must be changed when items are inserted into or deleted 
from lists of lists. The following discussions develop two 
subroutines that perform such changes: 

1. SET_ LINK, which assigns a value to the line pointer 
in a list component 


SET LINK Subroutine 


Purpose 


To assign a value to the link pointer of a component 
in a list of lists 


Reference 


SET_LINK(ADDRESS, L) 


Entry-Name Declaration 


DECLARE SET_LINK ENTRY(POINTER, 
POINTER); 


Meaning of Arguments 


ADDRESS — a pointer value that specifies the 
address of a component in a list of 
lists 





2. SET VALUE, which assigns values to the value 
pointer and type code in a list component 


SET _LINK Subroutine 
Figures 2.22A, 2.22 B, and 2.22C, present the SET _ LINK 
subroutine, which requires two arguments: 

1. Address of a list component 

2. Value to be assigned to the link pointer of the speci- 
fied list component 


— the value to be assigned to the link 
pointer of the list component 


Remarks 
The subroutine assumes that ADDRESS represents 
a valid address of a component in a list of lists. If 
ADDRESS is null, no assignment is made. 

Other Programmer-Defined Procedures Required 
None 


Method 


The pointer value of L is assigned to the link pointer 
of the specified component. 


Figure 2.22A. Description of the SET_LINK subroutine for assigning a value to the link pointer of a component in a list of lists 


SET ULINK: 

PROCEDURE (ADDRESS ,L)5 
DECLARE 

(ADDRESS, L) POINTER, 

1 COMPONENT BASEDCADORESS), 

2 TYPE CHARACTER(1), 

2 VALUE POINTER, 

2 LINK POINTERS 


IF 
ADDRESS = NULL 
THEN 
RETURNS; 
ADDRESS->LINK = L3; 
END 


SET_LINKS 
Figure 2.22B. The SET LINK subroutine 


SET_LINK(ADDRESS_LVT(L1),L2) 









Lists of Lists 
(before reference) 


ui: | Fetal bole IN 


Figure 2.22C. Example of a reference to the SET_LINK subroutine 
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SET _VALUE Subroutine 
Figures 2.23A, 2.23B, and 2.23C present the SET_ VALUE 
subroutine, which requires three arguments: 

1. Address of a list component 


SET_VALUE Subroutine 
Purpose 
To assign an address to the value pointer of a 
component in a list of lists and also to assign the 
associated type code 
Reference 
SET _VALUE(ADDRESS, V, T) 
Entry-Name Declaration 
DECLARE SET_VALUE ENTRY(POINTER, 
POINTER, 
CHARACTER (1)); 
Meaning of Arguments ~ 
ADDRESS — a pointer value that specifies the 


address of a component in a list of 
lists 





2. Value to be assigned to the value pointer of the speci- 


fied list component 


3. Value to be assigned to the a eee of the specified 
list component. 


— a pointer value that specifies the 
address of the value (data item or 
sublist) associated with the list 
component 


— the type code to be assigned to the 
type element in the list component 


Remarks 


‘The subroutine assumes that ADDRESS represents 
a valid address of a component in a list of lists. If 
ADDRESS is null, no assignment is made. 


Other Programmer-Defined Procedures Required 


None 


Method 


The pointer value of V is assigned to the value 
pointer of the specified component. The value of T 
is converted, if necessary, to a character string, 

and the leftmost character of the string is assumed to 
be the type code. | 


Figure 2.23A. Description of the SET VALUE subroutine for assigning an address to the value pointer of a component in a list of lists 


2 TYPE CHARACTER(1), IF 


SET_VALUE: 7 
PROCEDURE (ADDRESS »VoT)3 2 VALUE POINTER, | (Ta=z"D') € (TaetLe) 
DECLARE | 2 LINK POINTERS THEN | 
(ADDRESS, V) POINTER, IF RETURN: 
T CHARACTER(1)¢ ADORESS ADDRESS->TYPE = T; 


1 COMPONENT BASED(ADORESS)» THEN 
Figure 2.23B. The SET VALUE subroutine 


RETURNS 


= NULL | 
: ADDRESS->VALUE = V3 _ 
END . 
SET_VALUE $ 


List of Lists 
. (before reference) 


Subroutine 


Reference 


SET_VALUE(ADDRESS_NVT(L1,2), 
GET_VALUE(ADDRESS_LVT(L1)), 
GET_TYPE(ADDRESS_LVT(L1))) 





Figure 2.23C. Example of a reference to the SET_VALUE subroutine 
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Comparing Data Values of List Components 


To test the equality of lists of lists, it is often necessary to 
compare the data values of two list components. The fol- 
lowing discussion develops the EQUAL _D function for 

_ such comparisons. 


EQUAL _D Function 
Figures 2.24A, 2.24B, and 2.24C present the EQUAL _D 
function, which requires two arguments: 

1. The first list component involved in the test 

2. The second list component involved in the test 


The function returns ‘1’B when the list components 
contain the same data value, and ‘0’B when they do not. 


EQUAL_D Function ADDRESS2 — a pointer value that specifies the | 
address of the second list component 
Purpose involved in the test 


To test the equality of the data values associated 
with two list components Remarks 


Reference The function assumes that ADDRESS1 and 
3 ADDRESS2 specify valid addresses of components 
EQUAL _D(ADDRESS1, ADDRESS2) : in lists of lists. When both ADDRESS1 and 
ADDRESS2 are null, equality is assumed. 
Entry-Name Declaration 
Other Programmer-Defined Procedures Required 


DECLARE EQUAL DENTRY(POINTER, 
POINTER) None 
RETURNS(BIT(1)); 


Method 
Meaning of Arguments 
For equality, both list components must have type 
ADDRESS1 — a pointer value that specifies the code ‘D’, and both must have the same value 
address of the first list component pointer. The function returns ‘1'B when equality 
involved in the test occurs and ‘0’B when inequality occurs. 





Figure 2.24A. Description of the EQUAL _D function for testing the equality of the data values associated with two list components 


& (GET_TYPE(ADDORESS2)= *°0°) 


EQUAL_D: & (GET_VALUE(ADDRESS1) = 
PROCEDURE (ADDRESS1, ADDRESS2) GET_VALUE (ADDRESS2)?) 
RETURNS (BIT(19)3 THEN 
DECLARE RETURN(*1°B)5 
(ADORESS1 ,ADORESS2) POINTERS RETURN(*0*B)5s 
IF END 
(GET_TYPE(ADORESSLI= "D*) EQUAL_D3; 


Figure 2.24B. The EQUAL _D function 
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List of Lists 


Function Reference 


Function 


Value 


EQUAL_D(ADDRESS_NVT(L1,1),ADDRESS_NVT(L1,3)) 


EQUAL_D(ADDRESS_NVT(L1,1),ADDRESS_NVT(L1,2)) 


0B ( I=) 


EQUAL _D(ADDRESS_NVT(L1,2), ADDRESS_LVT(L1)) 


EQUAL_D(ADDRESS_LVT(L1),ADDRESS_LVT(L1)) 





Figure 2.24C. Examples of references to the EQUAL_D function 


Manipulating Top Level of a List of Lists 


All items in a list of lists may be processed by proceeding 
through the list in stages. With this approach, the first stage 
is restricted to the data items and sublists situated at the 
top level of the list. The second stage then deals with the 
top level of each sublist encountered during the first stage. 
Subsequent stages, in general, are concerned only with the 
sublists of the previous stage. When all sublists have been 
treated in this manner, processing for the entire list is 
complete. 

The following discussions develop bro tines and func- 
tions for manipulating the top level of a list of lists. These 
procedures are concerned with the following operations: 


1. Counting the number of values at the top level of a 


list of lists 
2. Inserting values into the top level of a list of lists 
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3. Obtaining values and their type codes from the top 
level of a list of lists 

4. Combining lists of lists at the top level 

5. Copying the top level of a list of lists in reverse order 


Counting Number of Values at Top 
Level of a List of Lists 


The size of a list of lists depends in part upon the number 
of values at the top level of the list. The following discus- 
sion develops the SIZE_ TOP function, which counts the 

values at the top level of a list. 


SIZE __TOP Function 

Figures 2.25A, 2.25B, and 2.25C present the SIZE TOP 
function, which requires the name of a list as its only argu- 
ment. The function returns a count of the data items and 
sublists at the top level of the specified list. 


-SIZE_ TOP Function 





Purpose 


To count the number of values at the top level of a 
list of lists 


Reference 
SIZE TOP(LIST) 
Entry-Name Declaration 
DECLARE SIZE_ TOP ENTRY(POINTER) 
RETURNS(FIXED 
DECIMAL (5)); 


Meaning of Argument 


LIST — the pointer variable that is the head of 
the list to be examined 


Remarks 


The maximum size is 99999. If LIST is null, a 
zero size is returned. 


Other Programmer-Defined Procedures Required 
GET _ LINK 

Method 
The function proceeds through the top level of LIST, 
counting the number of list components, until a 
null link pointer is encountered. The top level of 


LIST can contain any combination of data (D) 
values and list (L) values. 


Figure 2.25A. Description of the SIZE TOP function for counting 
the number of values at the top level of a list of lists 


SIZE_TOP: 
PROCEDURE (LIST) 
RETURNS( FIXED DECIMAL(5)); 
DECLARE 
(LIST,ADDRESS) POINTER, 
N FIXED DECIMAL(5); 
ADDRESS = LIST; 


DO 
N= 0 BY 13 
IF 
ADDRESS = NULL 
THEN 
RETURN(N); 
ADDRESS = GET_LINK(ADDRESS)$ 
END; 
END 
STZE_TOP; 


Figure 2.25B. The SIZE TOP function 


Function 


Function 
Value 


Reference 


SIZE_TOP(L1) 
SIZE_TOP(GET_LINK(L1)) 
SIZE_TOP(L2) 
SIZE_TOP(L3) 


SIZE_TOP(NULL) 





Figure 2.25C. Examples of references to the SIZE TOP function 
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Inserting Values Into Top Level of a List of Lists 


The creation of a list of lists requires the ability to insert 
data items and sublists into the list. The following discus- 
sions develop two procedures that perform such insertions 
at.the top level of a list of lists: 

1. INSERT_NVT, which inserts a value and its type 
code into a specified position at the top level of a list 

2. FORM_ BODY, which forms the body of a new list 
by extending the front of a given list with a specified value 


INSERT _NVT Subroutine 
Figures 2.26A, 2.26B, and 2.26C present the INSERT _ 
NVT subroutine, which requires four arguments: 
1. List in which an insertion is to be made 
2. Position of the insertion at the top level of the list 
3. Address of the value to be inserted 
4. Type code of the value to be inserted 


INSERT _NVT Subroutine Vv — the address of the value to be inserted 


Purpose — the type code (‘D’ or ’L’) of the © 
| | value to be inserted 
To insert a value into the nth position at the top 
level of a list of lists Remarks 


Reference | | When the list is null or N is less than two, V is 
, inserted into the first position at the top level of the 
INSERT NVT(LIST, N,V, T) | list. When N exceeds the size of the top level of the 
list, V is inserted into the last position. N cannot 
Entry-Name Declaration have a value greater than 99999. V may be null. 


DECLARE INSERT_NVT Other Programmer-Defined Procedures Required 
ENTRY (POINTER, FIXED DECIMAL (5), 
POINTER, CHARACTER (1)); SET_VALUE, SET_LINK, ADDRESS_NVT, and 
| ADDRESS_LVT : 
Meaning of Arguments 
Method 
LIST — the pointer variable that is the head of | 
the list to be processed Insertion of a value causes the size of the top level . 
| to increase by 1. The value previously at the nth 
— the position at the top level of the position becomes the (n+1)th value at the top level. 
list where the value is to be inserted | 





Figure 2.26A. Description of the INSERT_NVT subroutine for inserting a value into the nth position at the top level of a list of lists 
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INSERT_NVTs 


DECLARE 


IF 


PROCEDURE (LIST ONeVeT)$ 


T CHARACTER(1), 

N FIXED DECIMAL(5), 
(LIST,V,AODRESS1,ADDRESS2, 

AVAIL EXTERNAL) POINTER; 

4* IF LIST OF AVAILABLE STORAGE 
COMPONENTS IS EMPTY, PRINT MESSAGE 
AND RETURN. */ 

IF AVAIL = NULL THEN O00; 


LISTC*LIST OF AVAILABLE STORAGE IS 
EMPTY"); 

RETURN; END; 

/* ASSIGN VALUE V AND TYPE T TO 
FIRST COMPONENT IN AVAIL. */ 

CALL SET_VALUECAVAILsV,T)3 

/* TF LIST TS NULL OR N<2,_, INSERT 
FIRST COMPONENT OF AVAIL INTO 
FIRST POSITION OF LIST, ANDO 
RETURN. */ 


(LIST = NULLITON<2) 
THEN DO; 
ADDRESS] = LISTs LIST = AVAILS 


Figure 2.26B. The INSERT _NVT subroutine 


IF 
THEN 


ELSE 


AVAIL = ADDRESS_NVT(AVAIL,»2)3 

CALL SET_LINK(LIST,ADORESS1); 
RETURN; END; | 

/* OTHERWISE OBTAIN THE ADDRESS OF 
THE N-TH COMPONENT AT THE TOP OF 
LIST. #/ | 

ADDRESS2 = ADORESS_NVT(LIST»ND3 

/* IF N EXCEEDS SIZE OF LIST TOP, 
OBTAIN ADDRESS OF LAST COMPONENT AT 
TOP, ELSE OBTAIN ADDRESS OF (N-1) 
COMPONENT AT TOP..*/ 


ADDRESS2 


NULL 


ADDRESS1 ADDRESS_LUVTC(LIST)$ 
ADDRESS1 = ADORESS_NVTC(LIST,N=-1)5 
/* INSERT FIRST COMPONENT OF AVAIL 
INTO THE N-TH POSITION AT THE TOP 
OF LIST. */ 

CALL SET_LINK(ADDRESS1, AVAIL); 
ADDRESS1 = AVAIL; 

AVAIL = ADDRESS_NVTCAVAIL,2)3 

CALL SET_LINK(ADDORESS1,AODRESS2) 3 


END INSERT_NVTS$ 


Data Storage . Lists of Lists 
(before reference) 

ut | Feit Pepolul 

La: | Pe iY] Few 


INSERT_NVT(L4,5,N,‘D’) 


Figure 2.26C. Examples of references to the INSERT_NVT subroutine 
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receive a new value; the head points to the second compo- 


FORM BODY Function | nent at the top level of the new list. If the head is to point 
Figures ¢ 2.27A, 2.27B, and 2.27C present the FORM _ to the first component, the address value of the function 
BODY function, which requires three arguments: must be assigned explicitly to the head. | 

1. Address of the value to be inserted at the front of a Because the head of the old list is not modified auto- 
list matically by FORM_ BODY, the function can be thought 

2. Type code of the value to be inserted of as forming only the body of a new list. In fact, the built- 

3. List in which the insertion is to be made in function NULL can be used to specify the list in which 

insertion is to occur. In this case, no explicit list head is 

The function returns the address of the new first component involved, and FORM_ BODY generates the body of a new 
in the list, but the head pointer of the original list doesnot _list that contains one list component. 


— the type code (‘D’ or ‘L’) of the value 
inserted at the front of the new list 










FORM_BODY Function 


Purpose 


, LIST — the pointer variable that is the head of 
- To form the body of a new list of lists by extending the list to be extended at the front 
the front of a given list with a specified value, and with the new value 
also to obtain the address of the first list component 
in the new list Remarks 















Reference The effect of this function is equivalent to 
. inserting a value into the first position of LIST, 
FORM. BODY(V, T, LIST) except that the pointer value of LIST is not 
changed; instead, the address of the first list 
Entry-Name Declaration 7 component in the resulting list is returned as the 


| function value. 
DECLARE FORM_BODY ENTRY(POINTER, © 


CHARACTER(1), Other Programmer-Defined Procedures Required 
POINTER) | 
RETURNS(POINTER): SET _ VALUE, GET_LINK,and SET_LINK 


_ Meaning of Arguments Method 


V — the address of the value to be | _ Vand T are inserted into a new list component, 
inserted at the front of the new list which is linked to the front of the components in 
LIST. The pointer value of LIST is not changed. 


Figure 2.27A. Description of the FORM BODY function for forming the body of a new list of lists and returning the address of the first 
list component | 


FORM_BODY: RETURNS 
; PROCEDURE (V» Ty LIST) ENO; 
RETURNS (POINTER) /* LET P POINT TO FIRST COMPONENT 
DECLARE OF AVAIL LIST, AND LET AVAIL POINT 
T CHARACTER(1), | | TO SECOND COMPONENT OF AVAIL LIST.¥*/ 
(VeLISTsAVAIL EXTERNAL, P) POINTERS P = AVAILS$ 
/* IF LIST OF AVAILABLE STORAGE AVAIL = GET_LINK(AVAIL)s 
COMPONENTS IS EMPTY, PRINT MESSAGE /*® SET VALUE POINTER OF P COMPONENT 
AND RETURN. */ © EQUAL TO Ve AND SET LINK POINTER OF 
IF P COMPONENT EQUAL TO LIST. */ 
AVAIL = NULL CALL SET_VALUE(P.V,T)5 
THEN | CALL SET_LINK(P,LISTIS 
00; | /* RETURN ADDRESS OF P COMPONENT. */ 
PUT 7 RETURN(P)$ 
LIST(*LIST OF AVAILABLE STORAGE IS END 


EMPTY*)$ | | FORM_BODY ; 
Figure 2.27B. The FORM BODY function 
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Data Storage Lists of Lists 





(before reference) 


olx] PeplyN\ 












Function Reference Function Value (FV) Lists of Lists 





(after reference) 














FORM_BODY(M,’D’,L1) Address of component created 


for ‘1’ 












Address of component created 
for ‘2’ 


FORM_BODY(N,‘D’,L2) 












FORM_BODY(N,'D’,NULL) Address of component created 


for ‘2’ 














FORM_BODY(GET_VALUE(L3),‘L’,L1) Address of component created 


for duplication of value pointer 






in first component at top level 
of L3 






Figure 2.27C. Examples of references to the FORM_ BODY function 


Obtaining Values and Their Type Codes from 
Top Level of a List of Lists 


The following discussions develop two functions for obtain- 
‘ing values from the top level of a list of lists: 
1. GET_NVT, which gets the nth value at the top level 
of a list of lists 
2. GET_NTT, which gets the nth type code at the top 
level of a list of lists 
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GET_NVT Function 


Figures 2.28A, 2.28B, and 2.28C present the GET NVT 
function, which uses two arguments: 


1. Name of a list 


2. Position of a value at the top level of the list 


The function returns the address value of the value pointer 
in the specified position at the top level of the list. 


GET_NVT Function 


Purpose 


_ To obtain the address of the value associated with 
the nth component at the top level of a list of lists 


Reference 


GET_NVT(LIST, N) 


Entry-Name Declaration 


DECLARE GET_NVT ENTRY(POINTER, FIXED 
DECIMAL (5)) 
RETURNS(POINTER); 


Meaning of Arguments 


LIST — the pointer variable that is the head of 
the list to be processed 


N — the position of the retrieved value at 
the top level of the list 


Remarks 


A value of N less than one or greater than the size of 
the top level of the list causes a null address to be 
returned. 


Other Programmer-Defined Procedures Required 


ADDRESS_NVT and GET_ VALUE 


Method 


The following reference obtains the nth value at the 
top level of the list: 


GET_VALUE(ADDRESS_NVT(LIST, N)) 


The nth value at the top level remains in the list 
_ after its equivalent is returned. 


Figure 2.28A. Description of the GET NVT function for obtaining 
the nth value at the top level of a list of lists 
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GET_NVT(L1,3) Address of Z 


GET_NVT: | 
PROCEOURE (LIST, N) 
RETURNS (POINTER); 

DECLARE 
LIST POINTER, 
N FIXED DECIMAL(5)$ 
RETURN(GET_VALUE (ADODRESS_NVT 
(LIST SN) ))3 

ENO 
GET_NVT>$ 


Figure 2.28B. The GET _NVT function 












Function Function . 
Reference Value 





GET_NVT(L1,2) Address of sublist containing 
x and Y 


GET_NVT(L1,4) Null address 


Figure 2.28C. Ixamples of references to the GET NVT function 





GET NVT(L2,1) 






GET_NTT Function 


Figures 2.29A, 2.29B, and 2.29C present the GET _NTT 
function, which uses two arguments: 


1. Name of a list 


2. Position of a type code at the top level of the list 


The function returns the type code in the specified position 


at the top level of the list. 
























GET_NTT Function 


Purpose 





To obtain the type code (‘D’ or ‘L’) of the nth value 
at the top level of a list of lists 


Reference 


GET_NTT(LIST, N) 


Entry-Name Declaration 





DECLARE GET_NTT ENTRY(POINTER, FIXED 
DECIMAL (5)) 
RETURNS(CHARACTER 
(1)); 


Meaning of Arguments 


LIST — the pointer variable that is the head of 
the list to be processed 


N — the position of the retrieved type code 
at the top level of the list 
Remarks 


A value of N less than one or greater than the size of 
the top level of the list causes the type code ‘D’ to 
be returned. 


Other Programmer-Defined Procedures Required 


ADDRESS_NVT and GET_TYPE 


Method 


The following reference obtains the nth type code 
at the top level of the list: 





GET_TYPE(ADDRESS_NVT(LIST, N)) 


The nth type code at the top level remains in the 
list after its equivalent is returned. 


Figure 2.29A. Description of the GET_NTT function for obtaining 
the nth type code at the top level of a list of lists 


GET_NTT: 
PROCEDURE (LIST, N) 
RETURNS (CHARACTER(1))3 
DECLARE 
LIST POINTER, 
N FIXED DECIMAL(5)5 
RETURN(GET_TYPE( ADDRESS_NVT 
(LIST ND) )5 
END 
GET_NTTs; 


Figure 2.29B. The GET NTT function 


L2: NX 


Function Function 
Reference Value 


GET_NTT(L1,3) 
GET_NTT(L1,2) 


GET_NTT(L1,4) 


GET_NTT(L2,1) 





Figure 2.29C. Examples of references to the GET_NTT function 
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Combining Lists of Lists at Top Level 


A list can be extended by combining it at the top level with 
another list. The following discussions develop two proce- 
dures for such extensions: | 
1. LINKL, which links two lists of lists at the top level 
2. APPEND, which forms a new list of lists by dupli- 
cating the top level of one list and linking the top level of 
another list behind the duplicate 


LINKL Subroutine 

Figures 2.30A, 2.30B, and 2.30C present the LINKL sub- 
routine, which requires the names of two lists as its argu- 
ments. The subroutine links the last component at the top 
level of the first list to the first component at the top level 
of the second list. | 


LINKL Subroutine Remarks 

Purpose | When LIST1 is null, it becomes equal to LIST2. 
To link two lists of lists at the top level When LIST2 is null, LIST1 does not change. 

Reference Other Programmer-Defined Procedures Required 
LINKL(LIST1, LIST2) | ADDRESS_LVT and SET_LINK 

Entry-Name Declaration | Method 
DECLARE LINKL ENTRY (POINTER, POINTER); The following reference links the lists: 

Meaning of Arguments | SET_LINK(ADDRESS_LVT(LIST1), LIST2) 
LIST1 a the first list to be linked ! No list components are duplicated, and hese 


values of LIST1 and LIST2 are not changed. 
LIST2 — the list to be linked behind LIST1 | 


Figure 2.30A. Description of the LINKL subroutine for linking two lists of lists at the top level 


LINKL: 
PROCEDURE(LISTI,LIST2)$ 
DECLARE 
(LIST1L»LISTZ2) POINTERS 


LISTL = NULL 


| gat 
= 
~” 
= 
= 
" 


LIST2; 


CALL SET_LINK(ADDRESS_LVT(LIST1)> 
LIST2); 

END 
LINKL; 


Figure 2.30B. The LINKL subroutine 
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Lists of Lists 
(before reference) 







LINKL(L1,L2) 


LINKL(L3,L1) 


LINKL(L1,L3) 


Figure 2.30C. Examples of references to the LINKL subroutine 
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APPEND Function | : 
Figures 2.31A, 2.31B, and 2.31C present the APPEND 
function, which uses the names of two lists as its argu- 
ments. This function duplicates the top level of the first list 
and links the top level of the second list behind the dupli- 
cate. The function then returns the address of the first 
component in the new list. _ 

The APPEND function, unlike the previous procedure 
(LINKL), preserves the first list as an entity. 


APPEND Function LIST2 — the list to be appended behind the 
| | duplicate top level 

Purpose 

Remarks 


To form a new list of lists by duplicating the top 


level of one list and appending the top level of 
another list behind the duplicate top level, and also 
to obtain the address of the first list component in 
the new list. 

Reference 


APPEND(LIST1, LIST2) 


Entry-Name Declaration 


DECLARE APPEND ENTRY (POINTER, POINTER) 
RETURNS(POINTER); 


Meaning of Arguments 


LIST1 — the list whose top level is to be 
duplicated 


Figure 2.31A. Description of the APPEND function 


APPEND: 


When LIST1 is null, the address of the first list 
component in LIST2 is returned. The components 
in LIST2 are never duplicated. The address values 
of pointers LIST1 and LIST2 remain unchanged. 


Other Programmer-Defined Procedures Required 


FORM_BODY, GET_VALUE, GET_ TYPE, and 
_ GET_LINK 


Method 


The following recursive reference forms the new 
list: 


FORM_BODY(GET_VALUE(LIST1), 
GET_TYPE(LIST1), APPEND 
(GET_LINK(LIST1), LIST2)) 





PROCEDURE (LIST1, LIST2) 


RETURNS (POINTER) 


, RECURSIVE; 
DECLARE 


(LISTI,LIST2) POINTERS 


IF 


LIST = NULL 


THEN 


RETURN(LIST2)$ 

RETURN (FORM_BODY(GET_VALUE(LIST1), 

GET_TYPE(LIST1), 

APPEND(GET_LINK(LIST1)» LIST2)))3 
END 

APPEND; 


Figure 2.31B. The APPEND function 
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Lists of Lists 


(before reference) 


Se et eS 

u2: | Peel | Peezi 
o[x] Feolyi\ 

L3 


IN 


Function Function Value(FV) Lists of Lists 
Reference (after reference) 


APPEND(L1,L2) Address of duplicate component L1: ze POINT FD |W I\ 


specifying V 


APPEND(L2,L1) Address of duplicate component 
specifying sublist elements 
X and Y 
APPEND(L3,L1) Address of first component in L1 
| OPP PPPN 
APPEND(L1,L3) Address of duplicate component : | beolv] peolwh\ 
specifying V 
| Lev Pew 


Figure 2.31C. Examples of references to the APPEND function 











FV: 


L2: 


| Copying Top Level of a List of 
Lists in Reverse Order 


It usually takes less time to retrieve an item from the front 
of a list than from the end, because fewer items have to be 
traversed to reach the desired item. When more processing 
occurs at the end of list than at the front, it may be more 
efficient to reverse the list. 
The following discussions develop two subroutines for 
reversing a list of lists: | 
1. COPY _REVT, which copies the top level of a list of 
lists in reverse order and returns the address of the new list 
2. COPY REVT1, which is the recursive equivalent of 
COPY _REVT fe | 


COPY _REVT Function 
Purpose 


To copy the top level of a list of lists in reverse order 
and to return the address of the new list 


Reference 
COPY _REVT(LIST) 
Entry-Name Declaration 


DECLARE COPY_REVT ENTRY(POINTER) 
RETURNS(POINTER); 


Meaning of Argument 


LIST — the list whose top level is to be copied 
in reverse order 





Generating a new top-level list in reverse order generally 


_takes less time than relinking the top level of the original 


list. | | 


COPY _REVT Function 
Figures 2.32A, 2.32B, and 2.32C present COPY REVT, 
which requires the name of a list as its only argument. The 
function returns the address of the new list, which has been 
reversed at the top level. | 

Note that the function does not produce a distinct copy 
of the new list. Both the new and old lists share compo- 
nents at lower levels. 


Remarks 
Components at lower levels of LIST are not copied 
but are shared between the old and new lists. When 
LIST is null, a null address is returned. 


Other Programmer-Defined Procedures Required 


FORM_BODY, GET_VALUE, GET_ TYPE, and 
GET_LINK 


Method 


-GET_LINK obtains successive addresses of list 
components at the top level of LIST. 


GET VALUE and GET_TYPE obtain the value 
and type of each list component. 


FORM_BODY creates and links the components 
in the new top-level list. 


Figure 2.32A. Description of the COPY _REVT function for copying the top level of a list of lists in reverse order and returning the address of 


the new list. 


COPY_REVT: 
PROCEDURE (LIST) 
RETURNS (POINTERDS 
DECLARE 
(LIST,ADDRESS1,ADDRESS2) POINTERS 
ADDRESS1 = LIST; 
ADORESS2 = NULL3 


IF | 
ADORESS1 


NULL 


Figure 2.32B. The COPY REVT function 
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THEN 
RETURN(ADDRESS2)3 
ADDRESS2 = FORM_BODY(GET_VALUE 
(ADDRESS1), 
GET_TYPECADDRESS1), 
ADORESS2)3 : 
ADDRESS] = GET_LLINKCADDRESSIDS 
GO TO 
Ls 
END | 
COPY_REVTS 


Lists of Lists 
(before reference) 















SE Oe es Oo) TN 


Function 


Reference 





« D+PPTHPRIN 
v: OEE 





COPY_REVT(L1) Address of duplicate component 





specifying W 








COPY __REVTI(L2) Address of duplicate component 


specifying Z 


COPY __REVT(L3) Null address 


Figure 2.32C. Examples of references to the COPY _REVT function 
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COPY_REVT1 Function 

Figures 2.33A and 2.33B present the COPY. REVT1 
function, which uses recursive techniques to produce the 
same results as COPY_REVT in the previous discussion. 


COPY REVT1 Function 


Purpose 


To copy the top level of a list of lists in reverse order 
and to return the address of the new list 


Reference 
COPY _REVT1(LIST,NULL) 


Entry-Name Declaration 


DECLARE COPY _ REVT1 ENTRY (POINTER, 
POINTER) RETURNS(POINTER); 


Meaning of Argument 


LIST — the list whose top level is to be copied 
in reverse order 


Remarks 
Components at lower levels of LIST are not copied 
but are shared with the new list. When LIST is 
null, a null address is returned. 


Other Programmer-Defined Procedures Required 


FORM_BODY, GET _VALUE, GET_TYPE, and 
GET_LINK 


Method 


COPY _REVT1 performs the recursive equivalent 

of the method developed in the previous function 
COPY _REVT. COPY_REVT1 uses two pointer 
parameters. The first parameter (LIST) represents 
the list whose top level is to be copied. The second — 
parameter (ADDRESS) represents the new list; 
initially ADDRESS is null. COPY _REVT1 returns 
the value of the following recursive expression: 


COPY_REVT1(GET_LINK(LIST), FORM_BODY 
(GET_VALUE(LIST),GET_TYPE(LIST), 
ADDRESS)) 


Each level of recursion is fepminaree by a null fink 
address. 





Figure 2.33A. Description of the alternative function 
COPY REVT1 for copying the top level of a list of 
lists in reverse order and returning the address of the 
new list 3 
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COPY_REVT1=sPROCEDURE(LIST, AODRESS) 
RETURNS(POINTER) RECURSIVE; 
DECLARE (LIST, AODRESS) POINTER; 
IF LIST = NULL THEN RETURN( ADDRESS); 
RETURN(COPY_REVTL(GET_LINK(LIST), 
FORM_BOOY(GET_VALUE(LIST), 
GET_TYPE(LIST) ,ADDRESSII)3 


“END COPY_REVT1; 


Figure 2.33B. The COPY_REVT1 function 


Manipulating all Levels of a List of Lists 


So far, the procedures developed for processing items in a 
list of lists are restricted to individual items or to the items 
at the top level of a list. The following discussions develop 


_ subroutines and functions for manipulating all levels of a 


list of lists. These procedures are concerned with the fol- 
lowing operations: 

. Obtaining the first and last data values in a list of lists 
. Counting the data values in a list of lists 

. Deleting values from a list of lists 

. Copying lists of lists 

. Testing lists of lists 

. Replacing data values in a list of lists 


NMR WY = 


Obtaining First and Last Data 
Values in a List of Lists 


To obtain either the first or the last data value in a list of 
lists, it may be necessary to search sublists at many levels. 
The following discussions develop four functions for per- 
forming such searches: 

1, GET_FD, which gets the first, or leftmost, data value 
in a list of lists 

2. GET_ FDR, which is the recursive equivalent of 
GET _FD 

3. GET_LD, which gets the last, or rightmost, data 
value in a list of lists 

4. GET_LDR, which is the recursive ean of 


-GET_LD 


GET_FD Function 

Figures 2.34A, 2.34B, and 2.34C present the GET FD 
function, which requires the name of a list as its only argu- 
ment. The function returns the sc of the first data 
value in the list. 


GET_FDR Function 


Figures 2.35A and 2.35B present the GET FDR function, 


which uses recursive techniques to produce the same result 
as GET_FD in the previous discussion. 


GET_LD Function 
Figures 2.36A, 2.36B, and 2.36C present the GET LD 
function, which requires the name of a list as its only argu- 


ment. The function returns the address of the last data 
value in the list. 


GET_LDR Function 
Figures 2.37A and 2.37B present the GET_LDR function, 


which uses recursive techniques to produce the same result 
as GET LD in the previous discussion. 


GET_FD Function 
Purpose 


To obtain the address of the first (leftmost) value 
associated with a data component in a list of lists 


Reference 
GET_FD(LIST) 
Entry-Name Declaration 


DECLARE GET_FD ENTRY(POINTER) 
RETURNS(POINTER): 


Meaning of Argument 


LIST — the pointer variable that is the head of 
the list to be processed 


Remarks 
When LIST is null, a null address is returned. 
Other Programmer-Defined Procedures Required 


GET_TYPE and GET_VALUE 


Method 


When the first component at the top level of LIST 
contains a data address value (‘D’), this value is 
returned. When the first component contains a 
list address value (‘L’), this sublist is searched. 
Searching continues in this manner until the first 
data address value to the left is encountered. 


Figure 2.34A. Description of the GET _FD function for getting the 
first data item in a list of lists 





GET_FO: 
PROCEDURE (LIST) 
RETURNS (POINTER); 
DECLARE 
(LIST,ADORESS) POINTERS 
ADORESS = LISTS 
Ls 
IF 
GET_TYPE(ADDRESS)= *D* 
THEN : 
RETURN(GET_VALUE (ADDRESS) 13 
ADDRESS = GET_VALUE (ADDRESS) $ 
GO TO 
L3 
END 
GET_FD: 


Figure 2.34B. The GET FD function 











Function Function 

Reference Value 
GET_FD(L1) Address of V 
GET_FD(L2) Address of Z 
GET_FD(L3) Null address 
GET_FD(NULL) Null address 


Figure 2.34C. Examples of references to the GET_FD 
function | 
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GET FDR Function 


Purpose 


To obtain the address of the first (leftmost) value 
associated with a data component in a list of lists 


Reference 
GET FDR(LIST) 
Entry-Name Declaration 


DECLARE GET_FDR ENTRY(POINTER) 
RETURNS(POINTER); 


Meaning of Argument 





— the pointer variable that is the head 
of the list to be processed — 


Remarks 
When LIST is null, a null address is returned. — 
Other Programmer-Defined Procedures Required 
| GET TYPE and GET_VALUE 


Method 


GET_FDR performs the recursive equivalent of the 
previous function GET_ FD. 


Figure 2.35A. Description of the recursive function GET FDR for getting the first data item in a list of lists 


GET_FOR: 


PROCEDURE (LIST) 
RETURNS (POINTER) RECURSIVES 


DECLARE 


IF 


LIST POINTERS 


GET_TYPE(LIST) = "O° 


THEN 


RETURN(GET_VALUE(LIST)); 
RETURN(GET_FOR(GET_VALUE(LISTI)); 


ENO 
GET_FOR; 


Figure 2.35B. The GET FDR function 






GET_LD Function 





Purpose 


To obtain the address of the last (rightmost) value 
associated with a data component in a list of lists 





Reference 






GET_LD(LIST) 





Entry-Name Declaration 





DECLARE GET_LD ENTRY (POINTER) 
RETURNS(POINTER); 






Meaning of Argument 





LIST — the pointer variable that is the head 
| of the list to be processed 








Figure 2.36A. Description of the GET_LD function for getting the last data item in a list of lists 


Remarks 
When LIST is null, a null address is returned. 
Other Programmer-Defined Procedures Required 
ADDRESS_LVT, GET_TYPE, and GET_ VALUE 
Method 


When the last component at the top level of LIST 
contains a data address value (‘D’), this value is 
returned. When the last component contains a 
list address value (‘LL’), the sublist is searched. 
Searching continues in this manner until a sublist 
is encountered that contains a data address value 
in the last component of its top level. | 






GET_LD: GET_TYPE( ADDRESS) = *08 


PROCEDURE (LIST) THEN 
RETURNS (POINTER); RETURN(GET_VALUE (ADDRESS) ); 
DECLARE ADDRESS = GET_VALUE(ACDRESS); 
(LIST,AODRESS) PCINTER; GO TO 
ADDRESS = LIST; L; 
L: END 
ADDRESS = ACORESS_LVTCACORESS); GET_LD;. 


IF 
Figure 2.36B. The GET_LD function 











Function Function 
Reference Value 
GET_LD(L1) 7 Address of V 
GET_LD(L2) : Address of Z 
GET_LD(NULL) ; 


Figure 2.36C. Examples of references to the GET_ LD function 






Nult address 





GET_{tDR Function 


— the pointer variable that is the head of 
Purpose the list to be processed 


To obtain the address of the last (rightmost) value Remarks 
associated with a data component in a list of lists 


When LIST is null, a null address is returned. 
Reference 


Other Programmer-Defined Procedures Required 


GET_LDR(LIST) 
a | ADDRESS_LVT, GET_TYPE, and GET_ VALUE 
Entry-Name Declaration: 7 
Method 
DECLARE GET_LDR ENTRY(POINTER) 


RETURNS(POINTER); GET_LDR performs the recursive equivalent of the 


previous function GET LD. 
Meaning of Argument ~~ 





Figure 2.37A. Description of the recursive function GET_ LDR for getting the last data item in a list of lists 
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GET_LOR: aa 
PROCEDURE (LIST) 
| RETURNS (POINTER) RECURSIVE; 
DECLARE. | 
(LIST ,ADDRESS) POINTER: 
ADDRESS = ADDRESS_LVT(LIST); 
IF 
GET_TYPE( ADDRESS) = *O0* 
THEN 
RETURN(GET_VALUE( ADDRESS) )3 
RETURN(GET_LOR(GET_VALUE ( ADDRESS) 103 
END 
GET_LOR; 


Figure 2.37B. The GET LDR function 


COUNT_D Function 
Purpose | 
To count all the data (D) values in a list of lists 
Reference | 
COUNT_D(LIST) 
Entry-Name Declaration 
DECLARE COUNT_D ENTRY (POINTER) 
RETURNS(FIXED 
DECIMAL(5)); ~ 


Meaning of Argument 


LIST — the pointer variable that is the head of 
the list to be processed 


Remarks 


The maximum size is 99999. When LIST is null, 


Counting Data Values ina List of Lists 


The overall size of a list of lists is determined by the num- 
ber of data values at all levels of the list. The following 
discussion develops: the COUNT _D function for counting 
the number of data values throughout a list. 


COUNT _D Function | 

Figures 2.38A, 2.38B, and 2.38C present the COUNT _D 
function, which requires the name of a list as its only argu- 
ment. The function returns a count of all data values in the 
list. 


a zero size is returned. Only data items (‘D’) are 
counted. 


Other Programmer-Defined Procedures Required 


GET_TYPE, GET_LINK, and GET_VALUE 


Method 


When the first component at the top level of LIST 
contains a data item (‘D’), the following recursive 
expression is evaluated: 


1+ COUNT_D(GET_LINK(LIST)) 


When the first component contains a list item (‘L’), 
the following recursive expression is evaluated: 


COUNT_D(GET_VALUE(LIST)) + COUNT_D 
(GET_LINK(LIST)) 


Each level of recursion is terminated when 
GET_LINK returns a null address. 





Figure 2.38A. Description of the COUNT _D function for counting all the data items in a list of lists 


COUNT_DOs 
- PROCEDURE (LIST) 
RETURNS (FIXED DECIMAL(5)) 
RECURSIVE $ 
DECLARE 

LIST POINTERS 

IF 
LIST = NULL 

THEN 


Figure 2.38B. The COUNT_D function 
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RETURN(0); 
IF ! 
GET_TYPE(LIST) = "D* 
THEN | 
RETURN(14+COUNT_D. (GET_LINK(LIST)))3 
RETURN(COUNT_D (GET_VALUE(LIST)) + 
COUNT_D (GET_LINK(LIST) ))3 
END | 
-COUNT_D; 


ui: | Fev Pew 














L3: N 
Function Function 
Reference Value 


Figure 2.38C. Examples of references to the 
COUNT _D function 









Deleting List Components from a 
List of Lists 


The following discussions develop two subroutines for 
deleting list components from a list of lists: 

1. DELETE LIST, which deletes all components from 
a list of lists 

2. DELETE _NVT, which deletes the nth component 
from the top level of a list of lists 


DELETE_LIST Subroutine 

Figures 2.39A, 2.39B, and 2.39C present the DELETE _ 
LIST subroutine, which requires as its only argument the 
name of the list to be deleted. 


DELETE_NVT Subroutine 
Figures 2.40A, 2.40B, and 2.40C present the DELETE _ 
NVT subroutine, which requires two arguments: 

1. Name of a list of lists 

2. Position of a value at the top level of the list 


The subroutine deletes the value from the specified posi- | 
tion at the top level of the list. 


‘DELETE_LIST Subroutine 
Purpose 
To delete all values from a list of lists 
Reference 
DELETE _LIST(LIST) 
Entry-Name Declaration 
DECLARE DELETE_LIST ENTRY(POINTER); 
Meaning of Argument 


LIST — the list to be deleted _ 


Remarks 
LIST is null after deletion. 
Other Programmer-Defined Procedures Required 


GET_TYPE, GET_VALUE, GET_LINK, and 
SET_LINK 


Method 


DELETE _LIST is a recursive subroutine. When the 
value of the first component at the top level of the 
list is a data item (‘D’), the component is inserted 
into the list of available storage components AVAIL, 
and the next component, which has now become 
the first component at the top level, is examined. 
When the value of the first component is a list 

item (‘L’), the sublist (and any sublists within it) 

is deleted recursively. The component that contains 
the head of the deleted sublist is then inserted into 
the list of available storage components, and the 
next component at the top level is examined. These 
steps are repeated until the list becomes null. 


Figure 2.39A. Description of the DELETE LIST subroutine for 
deleting all values from a list of lists 
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OELETE_LIST: | | 
PROCEDURE (LIST) RECURSIVE: 
DECLARE | 
:  (LISTsS,AVAIL EXTERNAL) POINTER; 
L: | aa 
IF 
LIST = NULL 
THEN | 
RETURN; 
/* I& THE VALUE OF THE FIRST 
COMPONENT IS A SUBLIST, | 
RECURSIVELY DELETE THIS SUBLIST ANO 
PROCEED TO THE FOLLOWING 
STATEMENTS, WHICH TREAT THE 
COMPONENT THAT CONTAINS THE HEAD OF 
THE DELETED LIST AS A DATA (*0*) 
COMPONENT. */ 
IF 
GET_TYPE(LIST) = *L* 
THEN 
CALL DELETE_LIST (GET_VALUE(LIST))3 
/* OTHERWISE, THE VALUE OF THE 
FIRST COMPONENT IS A DATA ITEM. 
THEREFORE, INSERT THE COMPONENT 
INTO THE LIST OF AVAILABLE STORAGE 
COMPONENTS. */ 
S = AVAIL; 
AVAIL = LIST; 
LIST = GET_LINK(LIST); 
CALL SET_LINK(AVAIL,S)3 
/* DELETE NEXT COMPONENT. */ 
GO TO 
| L; 
END 
DELETE_LIST; 


Figure 2.39B, The DELETE LIST subroutine 





Lists of Lists 









(before reference) 


uo ODDEN 


DELETE _LIST({L1) 


DELETE _LIST(L2) 





DELETE _LIST(L3) 


Figure 2.39C. -Examples of references to the 
DELETE _LIST subroutine | 
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DELETE _NVT Subroutine 
Purpose 


To delete the nth value from the top level of a list of 
lists 


Reference 


DELETE NVT(LIST,N)- 


Entry-Name Declaration 


DECLARE DELETE_NVT ENTRY(POINTER, 
FIXED DECIMAL (5)); 


Meaning of Arguments 


LIST — the list from which the nth value at 
the top level is to be deleted 
N — an integer that specifies the position 
of the value to be deleted from the top 
level of the list 


Remarks 


No value is deleted when N is less than one or greater 
than the size of the top level. 


Other Programmer-Defined Procedures Required 


ADDRESS_NVT, GET_ TYPE, DELETE_LIST, 
GET_VALUE, GET_LINK, and SET_LINK 


Method 


When. the nth component contains a data item 
(‘D’), it is inserted into the list of available storage 
components AVAIL. When the nth component 
contains a list item ('L’), the sublist is deleted first, 
and then the nth component at the top level is 
‘inserted into AVAIL. 





Figure.2.40A. Description of the DELETE _NVT subroutine for 


deleting the nth value from the top level of'a list of 
lists 


OELETE_NVT: 
PROCEDURE (LIST,N)S 

DECLARE 
N FIXEO OECIMAL(5), 
(LIST,COMPONENT,S,AVAIL EXTERNAL) 
POINTERS; 
/* OBTAIN ADDRESS OF N-TH COMPONENT 
AT TOP OF LIST. #/ 
COMPONENT = ADORESS_NVT(LISTeN)s 
/* RETURN IF ADORESS OF N-TH 
COMPONENT IS NULL. */ 


IF 
CCMPONENT = NULL 

THEN 
RETURNS; 
/* IF THE VALUE OF THE N-TH 
COMPONENT IS A LIST, THEN DELETE 
THIS LIST. *#/ 

IF 


GET_TYPE( COMPONENT) = *L* 


Figure 2.40B. The DELETE NVT subroutine 


DELETE_NVT(L1,1) 


DELETE NVT(L1,2) 


DELETE _NVT(L1,3) 


DELETE _NVT(L2,1) 


Figure 2.40C. Examples of references to the DELETE NVT subroutine 





THEN 
CALL DELETE_LIST(GET_VALUE 
(COMPONENT) ); 
/* OTHERWISE THE VALUE OF THE N-TH 
COMPONENT IS A DATA ITEM. THEREFORE, 
INSERT THE N-TH COMPONENT INTO THE 
LIST OF AVAILABLE STORAGE 
COMPONENTS. *#/ 
S = AVAIL; AVAIL = COMPONENT; 

IF 
N= 1 

THEN 
LIST = GETLLINK(LIST); 

ELSE 
CALL SET_LINK(ADDRESS_NVT(LIST,N-1), 
GET_LINK (COMPONENT) )3$ 
CALL SET_LINKCAVAIL,S)$ 

END 

DELETE_NVTS$ 


Lists of Lists 


(before reference) 
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Copying Lists of Lists 


It is often necessary to create a distinct copy of a list of lists 
for working purposes, while retaining the original list. The 
second list can be an exact duplicate of the first, or it can 
contain modifications, such as having its sublists leveled, so 
that all its data values appear at the top level. The follow- 
ing discussions develop two functions for such duplication: 

1. COPY_LIST, which copies a list without modifica- 
tions | 

2. COPY _LEV, which copies a list with all sublists 
leveled 











COPY _LIST Function 


Purpose 


new list 

Reference 
COPY _LIST(LIST) 

Entry-Name Declaration 


DECLARE COPY _LIST ENTRY (POINTER) 
RETURNS(POINTER); 








Meaning of Argument 
LIST — the list to be copied 


Remarks 





Distinct components are created at all levels for the 
new list, so that no components are shared between 
the old list and the new list. When LIST is null, a 

null address is returned. 


To copy a list of lists and to return the address of the 
‘ \ 


Each function returns the address of the new list. Assign- 
ment of this address to a pointer variable is effectively 
equivalent to list assignment. 


COP Y_ LISTF unction 


- Figures 2.41 A, 2.41B, and 2 AIC present the COPY LIST 


function, which uses the name of a list as its only argument. 
The function returns the address of the duplicate list. 


COPY_LEV Function 

Figures 2.42A, 2.42B, and 2.42C present the COPY LEV 
function, which uses as an argument the name of the list to 
be copied with all sublists leveled. The function returns 
the address of the new list. 


Other Programmer-Defined Procedures Required 


FORM_BODY, GET_TYPE, GET_VALUE, and 
GET_LINK 


Method 














COPY _LIST is a recursive function procedure. 
When the first component at the top level of LIST 
specifies a data item (‘D’), COPY _LIST returns the 
value of the following recursive expression: 


FORM_BODY(GET_VALUE(LIST), ‘D’, 
COPY_LIST(GET_LINK(LIST))) 


When the first component at the top level of LIST 
specifies a list item (‘L’), COPY LIST returns the 


value of the following recursive expression: 


FORM_BODY(COPY_LIST(GET_VALUE 
(LIST)), ‘L’, COPY_LIST(GET_LINK(LIST))) 


Recursion is terminated by a null link address. 


Figure 2.41A. Description of the COPY _LIST function for copying a list of lists and returning the address of the new list 


COPY_LIST: 
- PROCEDURE (LIST) 
RETURNS (POINTER) RECURSIVE; 
DECLARE 
LIST POINTER; 


IF 
LIST = NULL 
THEN | 
RETURN (NULL); 
IF 


| GET_TYPE(LIST) = *D* 
Figure 2.41B, The COPY LIST function 
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THEN 
RETURN(FORM_BODY(GET_VALUE(LIST), 
pf, 

COPY_LIST (GET_LINK(LISTI)9)3 
ELSE | 

RETURN(FORM_BODY(COPY_LIST 

(GET_VALUE(LIST)), 

Le, 

COPY_LIST (GET_LINK(LISTII9)3 

END | 


COPY_LISTs 


Lists of Lists 
(before reference) 


L1: a Poi vi jo Iwi 










L3: N 


Function Value (FV) Lists of Lists 
| (after reference) 


ui: | Feoivt Feil 
Fv: | pepolvy Peto wi 


Function 
Reference 


COPY _LIST(L1) 


COPY _LIST(L2) 

















Address of duplicate component 





specifying V 








Address of duplicate component 










specifying sublist elements 
X and Y 


COPY _LIST(L3) Null address 


Figure 2.41C. Examples of references to the COPY LIST function 
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COPY_LEV Function 
Purpose 


To copy a list of lists with all sublists leveled and to 
return the address of the new list © 


Reference 
COPY_LEV(LIST,NULL) 
Entry-Name Declaration © 


DECLARE COPY_LEV ENTRY (POINTER, 
POINTER) RETURNS(POINTER); 


Meaning of Argument 
LIST — the list to be copied 

Remarks 
The new list contains only data items (‘D’). Each 
sublist in LIST is replaced in the new list by a 
linked sequence of the data items contained in the 


sublist. When LIST is null, a null address is 
returned. 


new list 


COPY_LEV: 


Other Programmer-Defined Procedures Required 


FORM_BODY, GET_TYPE, GET_LINK, and 


GET VALUE 


Method 


COPY _LEV is arecursive function procedure that 
uses two pointer parameters. The first parameter 
(LIST) represents the list to be copied. The second 
parameter (ADDRESS) represents the new list; 
initially, ADDRESS is null. When the first 
component at the top level of LIST isa data item 
(‘D’), COPY LEV returns the pointer value of the 
following recursive expression: 


FORM_BODY(GET_VALUE(LIST), ‘D’, 
COPY _LEV(GET_LINK(LIST), ADDRESS)) 


When the first component at the top level of LIST 
is a list item (‘L’), COPY LEV returns the value of 
the following recursive expression: 


COPY_LEV(GET_VALUE(LIST), COPY_LEV 
(GET_LINK(LIST), ADDRESS)) 


Each level of recursion is terminated by a null link 
address in V LIST. 


Figure 2.42A. Description of the COPY LEV function for: ‘copying a list of lists with all sublists leveled and returning ‘the ies of the 


PROCEOURE(LIST,AODRESS): = 
RETURNS (POINTER) RECURSIVE: 


DECLARE 
(LIST, ADDRESS) POINTER; 
IF 
LEST = NULL 
THEN nt 
_- RETURN( ADDRESS); 
IF eS fe | 
| GET_TYPEC(LIST) = *p® 
THEN | : 
RETURN( FORM_BODY(GET_VALUE(LIST), 
"D%, ae 
COPY_LEV(GET_LINK(LIST) ,ADORESS))); 
RETURN(COPY_LEV(GET_VALUE(LIST), 
COPY_LEV(GET_LLINK(LIST) ,ADDRESS)))3 
END 


COPY_LEV; 


Figure 2.42B. The COPY LEV function 





COPY _LEV(L1) 


COPY _LEV(L2) 






Address of duplicate 
component specifying V 






L 


NO 


Address of duplicate 
component specifying O 


Figure 2.42C. Examples of references to the COPY _LEV function 


Testing Lists of Lists 


The following discussions develop two functions for per- 
forming tests on lists of lists: 

1. EQUAL _L, which tests two lists for equality 

2. MEMBER, which tests for the presence of a specified 
data value in a list of lists 


EQUAL _L Function 
Figures 2.43A, 2.43B, and 2.43C present the EQUAL L 
function, which uses the names of two lists for its argu- 


Lists of Lists 
(before reference) 





| L pele] Pielet peels] Pitt Flu 
| Dele ole Pols] bb breN 


ments. When the two lists are equal, the function returns 
‘1B; otherwise, ‘O’B is returned. 


MEMBER Function 
Figures 2.44A, 2.44B, and 2.44C present the MEMBER 
function, which uses two arguments: 

1. Address of a data item 

2. Name of a list of lists 


When the data item is a member of the list, the function 
returns “1’B; otherwise, it returns ‘O’B. 
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EQUAL_L Function 
Purpose 
To test two lists of lists for sqaality 
Reference 
EQUAL_L(LIST1, LIST2) 
Entry-Name Declaration 
DECLARE EQUAL_L ENTRY(POINTER, 
| POINTER) 


RETURNS(BIT(1)); 


Meaning of Arguments 


LIST1 — the first list to be tested for equality 
~LIST2 — the second list to be tested for 
- equality 
Remarks: 


When the lists are equal, EQUAL _L returns the 
value ‘1B. When the lists are not equal, ‘0’B is 
returned. For equality, both lists must be linked 
identically, and corresponding data components 
(‘D’) must contain the same value pointers. Both 


lists can share common components. Two null 
lists are considered equal. 


Other Programmer-Defined Procedures Required 


EQUAL_D, GET_TYPE, GET_VALUE, and 
GET_LINK 


Method 


EQUAL_L isa recursive function. When both lists 
are null, ‘1’B is returned. When one of the lists is 
null and the other is not, ‘0’B is returned. When the 
first component at the top level of each list has 
type ‘D’, the value of the following recursive 
expression is returned: 


EQUAL_D(LIST1, LIST2) & EQUAL_L 
(GET_LINK(LIST1),GET_LINK(LIST2)) 


When the first components have type ‘L’, EAUAL_L 
returns the value of the following recursive 
expression: | | 


EQUAL_L(GET_VALUE(LIST1), GET_VALUE 
(LIST2)) & EQUAL_L(GET_LINK(LIST1), 
GET_LINK(LIST2)) 


When the first components have unequal types, 
‘O’B is returned. Each level of recursion is terminated 
by a null link address in either list. | 


Figure 2.43A. Description of the EQUAL_L function for testing the equality of two lists of lists 


EQUAL_L: 
PROCEDURE (LIST1,LIST2) 
“RETURNS (BIT(1)) RECURSIVES 


DECLARE 
(LISTL,LIST2) POINTER; 
(LISTL = NULL) & (LIST2 = NULL) 
THEN | 
RETURN(*1°B)5 
IF 
(LISTL = NULLIF(LIST2 = NULL) 
THEN 
RETURN(*0°B)$ 
IF 


(GET_TYPE(LIST1) = *D*) & 
(GET_TYPE(LIST2) = "O*) 


Figure 2.43B. The EQUAL L function 
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THEN | 
RETURN( EQUAL_DILISTI,LIST2) 
& EQUAL_L (GET_LLINK(LISTL), 
GET_LLINK(LIST2)))3 

IF | 

GET_TYPE(LIST1) = GET_TYPE(LIST2) 

THEN | 
RETURN( EQUAL_L (GET_VALUE(LIST1), 
GET_VALUE(LIST2)) 
& EQUAL_L (GET_LLINK(LIST1), 
GET_LLINK(LIST2)))3 

| RETURN(*0*B)3 

ENO. | | | 


EQUAL_L; 
















Function Function 

Reference Value 
EQUAL_L(L1,L2) 1'B (=) 
EQUAL_L(L1,L3) 0'B ( I=) 
EQUAL_L(L4,L5) ‘0'B ( I=) 
EQUAL_L(L5,L6) ‘0'B ( |=) 


Figure 2.43C. Examples of references to the EQUAL_L 


function 
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MEMBER Function 
Purpose 


To test for the presence of a data item in a list of 
lists 


Reference 
MEM BER(D, LIST) 
Entry-Name Declaration | 


~ DECLARE MEMBER ENTRY(POINTER, POINTER) 
RETURNS(BIT(1)); 


Meaning of Arguments 


D — the address of the data item being 
tested for 
LIST — the list being tested for the presence 
of D- 
Remarks. 


When D is in LIST, MEMBER returns ‘1’B; 
otherwise, it returns ‘O’B. 


Other Programmer-Defined Procedures Required 


GET_TYPE, GET VALUE, and GET_LINK 
Method 


MEMBER is a recursive function. When LIST is 
null, ‘O’B is returned. When the first component at 
the top level of LIST has type ‘D’ and its value 
equals D, MEMBER returns ‘1’'B. When the first 
component at the top level of LIST has type ‘D’ but 
its value does not equal D, MEMBER executes the 
following statement: 


IF MEMBER(D, GET_LINK(LIST)) 
| THEN RETURN(‘1‘B); ELSE RETURN(‘0’B); 
When the first component at the top level of LIST 
has type ‘L’, MEMBER executes the following 


statements: 


IF MEMBER(D, GET_VALUE(LIST)) THEN 
RETURN(‘1'B); 


IF MEMBER(D, GET_LINK(LIST)) 
THEN RETURN(‘1’B); ELSE RETURN(‘0(B); 


Each level of recursion is terminated by a null link 
address. 


Figure 2.44A. Description of the MEMBER function for testing a list of lists for the presence of a data item 


MEMBER: | 
PROCEDURE (Dy, LIST) 
RETURNS (BIT(1)) RECURSIVEs 
DECLARE 

(0, LIST) POINTER; 


IF 
LIST = NULL 
THEN a 
RETURN(*0°B)5 
IF 
GET_TYPE(LIST) =*D* 
THEN 
IF 
GET_VALUE(LIST) = D 
THEN 


RETURN(°1°B);5 


Figure 2.44B,. The MEMBER function 
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ELSE; 
ELSE 


IF 
MEMBER(D, GET_VALUE(LIST) ) 


THEN 
RETURNG91°B)5 


IF 
MEMBER(D, GET_LINK(LIST)) 


THEN 
RETURN(*1°B)$ 
SE , 
RETURN(*0°B)5 


MEMBER; 


Lists of Lists 


Mag lite LIN 


Function Function 
Reference Value 


MEMBER(GET_NVT(L2,2),L1) ‘1'B 

(X in L1) 
MEMBER(GET_NVT(L2,1),L1) ‘O'B 

(T not in L1) 


Figure 2.44C. Examples of references to the MEMBER function | 


Replacing Data Values in a List of Lists 


The following discussion presents the REPLACE subroutine, 
which replaces each occurrence of a data value in a list of 
lists with another data value. 


REPLACE Subroutine 
Figures 2.45A, 2.45B, and 2.45C present the REPLACE 
subroutine, which uses three arguments: 

1. Address of the data value being replaced 

2. Address of the new data value 

3. Name of the list of lists in which the replacement 
occurs 
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REPLACE Subroutine | 
Purpose 


To replace each occurrence of a data item in a list 
of lists with another data item 


Reference 
REPLACE(D1, D2, LIST) 


Entry-Name Declaration 


DECLARE REPLACE ENTRY(POINTER,POINTER, 
POINTER); 


Meaning of Arguments 


Di — the address of the data item to be 
replaced | 

D2 — the address of the data item replacing | 
D1 

LIST — the list within which replacement 
occurs | 


Remarks 


D1 and D2 must be addresses of data items and not 
of lists (D1 or D2 can be null). 


Other Programmer-Defined Procedures Required 


GET_TYPE, GET_VALUE, GET_LINK, and - 
SET_VALUE 


Method: 


REPLACE is a recursive subroutine. When LIST is 
null, no replacement occurs. 


When the first component at the top level of LIST 
has type ‘D’ and its value equals D1, value D2 
replaces D1. When the first component at the top 
level of LIST has type ‘L’, the sublist is processed 
recursively with the following statement: 


CALL REPLACE(D1, D2, GET_VALUE(LIST)); 


In both cases, the remainder of the list is processed 
recursively with the following statement: 


CALL REPLACE(D1, D2, GET_LINK(LIST)); 


Figure 2.45A. Description of the REPLACE subroutine for replacing each occurrence of a data item in a list of lists with another data item 


REPLACE: 


DECLARE 


PROCEDURE (01,02,LIST) RECURSIVE; 


(D1,02,LIST) POINTERS 


IF 
LIST = NULL 
THEN | 
RETURN; 
IF 


GET_TYPE(LIST) 


THEN 
IF 


= "oe 


GET_VALUE(LIST) = 01 


THEN 


CALL SET_VALUE(LIST,D2,*D'); 


ELSE; 
ELSE 


CALL REPLACE (01,02, 
GET_VALUE(LIST)); 


END 7 
REPLACE $ 


CALL REPLACE (01,02eGET_LINK(LISTID; 


Figure 2.45B. The REPLACE subroutine 
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Data Lists of Lists 
Storage (before reference) 





Figure 2.45C. Examples of references to the REPLACE subroutine 


USING LISTS OF LISTS 


Lists of lists provide the same reductions in data duplication 
and data movement that are available with pointer lists. Un- 
like pointer lists, however, lists of lists eliminate the need 
to know exactly how many lists a program will require dur- 
ing execution. New lists can be generated as the need arises 
for them during program execution, and they can be 
treated as sublists within a major list of lists. 

The following discussions provide two examples of this 
flexibility in list generation. | 

The first example shows how a list of lists may be used 
to represent a binary tree that has an arbitrary number 
of branches. It then applies the tree list to a sort applica- 
tion. | 

The second example creates an index from descriptor 

words contained in a set of catalog cards. The index is 
organized as a list of lists. Each sublist specifies a descriptor 
word and the catalog cards that contain the descriptor. The 
number of descriptors, and consequently the number of sub- 
lists, is arbitrary. 


Sorting With a Binary Tree 
The following discussion shows how a list of lists may be 


used to represent a binary tree and how the resultant tree 
list may be applied to sorting. 


Figure 2.46A applies a tree sort to the seven integers 4, 
2,6,3,1,5, and 7, received in that order. Each node of the 
tree contains an integer. The left branch of each node 
always leads to a smaller integer, and the right branch 
always leads to a larger integer. Successive integers enter the 
tree at the bottom, as shown in Figure 2.46A. | 

The shape of the tree will vary according to the original 
order of the integers. If the integers are already in ascending 
sequence, the tree will contain right branches only. Simi- 
larly, a descending sequence will produce left branches 
only. 

Although the placement of the integers in the binary tree 
of Figure 2.46A does not correspond to a conventional 
sort arrangement, the integers are readily retrieved in sort 
order. The smallest integer is reached by always taking the 
left branch of successive nodes. Taking the right branch of 
successive nodes leads to the largest integer. Appropriate 
combinations of left and right branches lead to the other 
integers. Later discussions develop recursive procedures for 
performing such retrieval. 

Figure 2.46B contains a list representation of the binary 
tree constructed in Figure 2.46A. This list uses three list 
components for each node in the tree. The first component 
specifies the data value at the node. The second compo- 
nent is an L-component whose value pointer branches to 
the next node on the left. The third component is also an 
L-component whose value pointer branches to the next 
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Data to be Arranged in Binary Tree 


4,2,6,3,1,5,7 


Figure 2.46A. Sorting data items by arranging them in a binary tree 
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Figure 2.46B. Representing a binary tree with a list of lists 


node on the right. When a node is not followed by another 
node (either on the left or on the right), the appropri- 
ate L-components contain null value pointers. 
Representation of each node as a sublist within a list of 
lists allows the main list to contain an arbitrary number of 
nodes. It also frees the programmer from having to know 
exactly how many nodes will be required and what their 
arrangement will be during program execution. 


The remainder of this discussion shows how a tree list 
(as illustrated in Figure 2.46B) may be used to sort succes- 
sive sets of input cards, where each set contains an arbitrary 
number of cards. The cards are assumed to have the fol- 
lowing structure: 


1 CARD, 
2KEY CHARACTER(3) 
2 DATA CHARACTER(77) 


Sorting occurs in ascending sequence on KEY. Each set of 
cards is terminated by a card that contains three asterisks 
(***) in its KEY field. 

To simplify the organization of the sort program, a main 
procedure (T_ SORT) is designed to operate with a func- 
tion procedure (NODE) and two subroutine procedures 
(ADD_NODE and T_ PRINT): 

1. NODE creates a three-component node for the list 
representation of a binary tree and returns the address of 
the leftmost component in the node. 

2. ADD NODE inserts a node (created by NODE) into 
the list representation of a binary tree in sort order. 









NODE (N) 


PeLKEN FENN 


3. T_PRINT prints in sort order the data values speci- 
fied in the list representation of a binary tree. : 


Figures 2.46C and 2.46D present the NODE function, 
which uses the address of a card as its only argument. The 
function generates a three-component node for the card, 
assigns the address of the card to the value pointer of 
the leftmost component, and returns the address of the 
leftmost component. The value pointers of second and 
third components as well as the link pointer of the third 
component are null. The function creates the node by 
using three nested references to the function FORM _ 
BODY, which was developed earlier. 


NODE: 
PROCEDURE (CARD_ADDRESS) 
RETURNS (POINTER); 

DECLARE 
CARD_ADORESS POINTER, 
NULL_PTR POINTERS 
NULL_PTR = NULL3 
RETURNCFORM_BODY (CARD_ADDRESS, *D*%, 
FORM_BODY(NULL_PTR, *L*, 
FORM_BODY(NULL_PTR, *L*, 
NULL_PTR))))3 

END 
NODE$ 


Figure 2.46C. The NODE function 


To simplify the diagrams in Figure 2.46D, single-position 
character strings are used instead of 80-position cards. This 
simplification is also used in the remaining diagrams of the 
discussion. 


Data ; 
Storage. 





Address of leftmost component 





in node generated by function 













Address of leftmost component 


in node generated by function 








Figure 2.46D. Examples of references to the NODE function 
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Figures 2.46E and 2.46F present the ADD_NODE sub- 


routine, which is a recursive ye procedure that uses two - 
arguments: 

1. Address of a card that contains KEY and DATA 
fields as described earlier 

2. Name of a list that represents a binary tree 


ADO_NOODE =: 
PROCEDURE (CARD_ADDRESS, TREE) 
RECURSIVE; 
- DECLARE 
1 CARD_IMAGE BASED( NODE —CARD)» 
2 KEY CHARACTER(3), 
2 DATA CHARACTER(77), 
NODE_CARD POINTER, 
(TREE »CARD_ADDRESS »LEFT» RIGHT) 


POINTER; 
IF : 
TREE = NULL 
THEN | 
00; : 
TREE = NODE(CARD_ADDRESS); RETURN; 
-END3 
NODE_CARD = GET _VALUE (TREE); 
LEFT = GET_LINK(TREE); 
RIGHT = GET_LINK(GET_LINK(TREE)) 
IF 


CARD_ADDRESS->KEY<NODE_CARD->KEY 
Figure 2.46E. The ADD NODE subroutine 


The subroutine creates a node for the card by invoking — 
the NODE function and then links the node to the bottom 
of the specified tree list. The KEY field of the card deter- 
mines where the new node is inserted into the tree list. 


THEN 
IF a 
GET_VALUE(LEFT) = NULL 
THEN | 
CALL SET_VALUE(LEFT,NOOE 
(CARD_ADDRESS)»*L*)$ 
ELSE . | 
CALL ADO_NODE(CARD_ADDRESS, 
GET_VALUE(LEFT));$ 
ELSE : 
IF | 
GET_VALUE(RIGHT) = NULL 
THEN 


CALL SET_VALUE(RIGHT,NODE 
(CARD_ADDRESS),°L*);5 
ELSE 
CALL ADD_NODE(CARD_ADDRESS, 
GET_VALUE (RIGHT })3 
END 
ADO_NODE ; 


Data | | Tree Lists ? 
| Storage : | (before reference) 


Dia ei AR A aft rn ee Sh ty 
Subroutine 


Reference © 


ADD_NODE(M,L1) 


ADD_NODE(N,L2) 





Tree Lists 


(after reference) 


ut | pee IN 


ble et N_PENN 


olay Feet TINA 
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Figure 2.46F. Examples of references to the ADD_ NODE subroutine 


68 


Figures 2.46G and 2.46H present the T_ PRINT sub- 
routine, which is a recursive procedure that uses the name 
of a tree list as its only argument. The subroutine prints the 
cards specified at the nodes of the tree list. The cards are 
printed in sort order on the standard system-ouput file, 
SYSPRINT. 


TLPRINTs 
PROCEDURE (TREE) RECURSIVE: 


DECLARE 
1 CARD_IMAGE BASED(NODE_CARD), 


2 KEY CHARACTER(3)+ 
2 DATA CHARACTER(77), 
NODE_CARD POINTER,» 
(TREE,LEFT»RIGHT) POINTERS 
IF 
TREE = NULL 
THEN 


RETURN; 
NODE_CARD = GET_VALUE(TREE); 


LEFT = GET_VALUE(GET_LINK(TREE)) 
RIGHT = GET_VALUE(GET_LINK 
(GET_LINK (TREE) ))5 

CALL T_PRINT(LEFT)$ 


PUT 
EDI T(NODE_CARD->CARD_IMAGE)(A)D$ 


PUT 
SKIP 
CALL T_PRINT(RIGHT)$ 


END 
TLPRINT$ 


Figure 2.46G. The T_PRINT subroutine 


Actual sorting is under control of the main procedure 
T_SORT, which appears in Figure 2.461. T_ SORT invokes 
the AREA OPEN subroutine (developed earlier) to create 
a list of available storage components (AVAIL) in the 


storage area called LIST AREA. Cards are read from the 
standard system-input file, SYSIN, and printed unsorted on 
the standard system-output file, SYSPRINT. As each card 
is read, based storage is allocated for it in the area called 
CARD_ AREA. Reading stops when the KEY field of a 
card contains three asterisks (***). Should the number of 
cards in a set exceed the capacity of CARD AREA, the 
remaining cards in the set are skipped, and only those cards 
allocated in CARD AREA are sorted. 


T_SORT: 
PROCEDURE ; 

DECLARE | 

CARD, 

KEY CHARACTER(3), 

DATA CHARACTER(77), 

CARD_IMAGE BASED(CARD_ADDRESS), 

KEY CHARACTER(3), 

DATA CHARACTER(77), 
(CARO_AREA, LIST_AREA) AREA, 
CARD_ADORESS POINTER, 
(TREEsAVAIL EXTERNAL) POINTERS 
/* WHEN ALL SETS OF INPUT CARDS 
HAVE BEEN SORTED, TERMINATE 
PROGRAM. */ 

ON ENDFILE (SYSIN) 

GO TO 
END_T_SORT;$ 
/* WHEN THE NUMBER OF CARDS IN A SET 
EXCEEDS THE CAPACITY OF CARD_AREA, 
SKIP REMAINING CARDS IN SET, AND 
PRINT THE FOLLOWING MESSAGE AFTER 
LAST CARD: **** INPUT EXCEEDED AREA 
CAPACITY*®. THEN PRINT CONTENT OF 
TREE LIST IN SORT ORDER. */ 
ON AREA 


NM Rm N/A 


BEGINS 
SKIPs 
GET 
| EDIT (CARO) (AC3), ACTT))D$ 
IF 
CARD.KEY = *eeee 


sa gO ete 
De PIN eI 
olay Peel | PeUNN 
oh] PiLN 


Subroutine Subroutine 
Reference Printout : 


T_PRINT(L1) 





Figure 2.46H. Example of a reference to the T_ PRINT subroutine 
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THEN 
DO; 
PUT a 
LIST(*s** INPUT EXCEEDED AREA 
CAPACITY*)3 
PUT 
SKIP$ 
GO TO 
PRINT_OUTPUT; 
END; : 
€LSE 
GO TO 
. SKIP3 
END $ 
4* INITIALIZE. */ 
TREE, AVAIL = NULL3 
LIST_AREA = EMPTY3 
CALL AREA_OPEN(LIST_AREA,AVAIL)$ 
4* GET NEXT SET OF INPUT CARDS. 
PRINT EACH CARD AS IT IS READ, ANDO 
CREATE A NODE FOR IT IN TREE LIST. #/ 
START 
GET 
EDIT(CARD)(A(3) gACTTID3 
PUT 
PAGE 
LIST(C*T_SORT INPUT:*)3 
PUT 
SKIP$ 
PRINT_INPUT?: 
PUT 
EDIT(CARD)(A)3 
PuT 
SKIP$ 
IF 
CARD.KEY = *euut 
THEN 
GO TO 
PRINT_OUTPUTS | 
ALLOCATE CARD_IMAGE IN(CARD_AREA) 
SET(CARD_ADDRESS)3 
CARD_ADDRESS->CARD_IMAGE = CARD; 
CALL ADD_NODE(CARD_AODRESS, TREE); 
GET 
EDIT(CARD) (A003) -A0771))3 
GO TO 
PRINT_INPUT>$ 
4* PRINT TREE LIST IN SORT ORDER, */ 
PRINT_OUTPUT: 


PUT 

PAGE | 

LIST(*T_SORT QUTPUT:*)3 
PUT 

SKIP; 

CALL T_PRINT(TREE);$ 
PuT | 


EDT T (CARD) (AD 
/* CLEAR CARD_AREA AND TREE LIST,*#/ 
J*THEN PROCESS NEXT SET OF INPUT */ 
4* CARDS. | */ 
CARD_AREA = EMPTY; 
CALL DELETE_LIST(TREE)$ 
GO TO 
STARTS 
END_T_SORT= 
END : 
T_SORTS 


Figure 2.461. The T SORT procedure 
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The address of each card in CARD_ AREA is used to” 
form a node in the tree list:called TREE. The ADD_NODE 


subroutine inserts the node into TREE, as described earlier. 


When TREE contains a node for each card, the cards are 
printed in sort order by the T_PRINT subroutine. A sample 
printout appears in Figure 2.46J. 


T_SORT OUTPUT: 
1 ONE 

2 Two 

3 THREE 

4 FOUR | 

5 FIVE 

6 SIX 

7 SEVEN 

KX 


Figure 2.46J. Printout from T SORT and T PRINT 


Before the next set of input cards is sorted, CARD _ 
AREA and TREE are cleared. Processing is terminated 
when an end-of-file condition occurs on the standard 
system-input file, SYSIN. | 

In summary, a tree list permits varying numbers of input 
cards to be sorted with a minimum of data movement and 
data duplication. 


Indexing Catalog Cards 


The use of a list of lists to index catalog cards is illustrated 
in Figures 2.47A through 2.47H. To avoid complexity, the 
discussion uses a simplified version of a catalog card, as 
shown in Figure 2.47A. The first ten columns of each card 
contain an accession number, which consists of any combin- 
ation of characters acceptable to the computer. In the case 
of a book catalog, the accession number might correspond 
to a Dewey decimal number; or it might serve as a part 
number for a catalog of machine parts. It could also repre- 
sent the identification number used in an art collection. 


INPUT TO INDEX: 


T2-XY4-16 PHOTOGRAPH BLACK WHITE LARGE 
AQ-1L7-RZ PAINTING BLACK WHITE SMALL 
Y¥9-016-X8 SCULPTURE MARBLE BLACK SMALL 
¥8-123-X7 SCULPTURE MARBLE WHITE MEDIUM 


Figure 2.47A. Input to INDEX 


The remaining 70 columns of each card contain descrip- 
tive information about the item ‘being cataloged. This 
information consists of descriptive words (descriptors) that 
specify particular features of the item being cataloged. For 
this discussion, a descriptor cannot exceed ten characters _ 
in length, but it can contain any combination of charac- 
ters and need not be restricted to a word. The number of 


descriptors in a card is arbitrary, but at least one blank 
character must separate successive descriptors. When a card 
cannot hold all the desired descriptors, additional cards may 
be used, provided that they contain the same accession 
number. 

The four catalog cards in Figure 2.47A provide informa- 
tion about art objects, and the index produced for these 
cards appears in Figure 2.47H. The descriptors are printed 
in sort order, and each descriptor is followed by all cards 
that contain the descriptor. The cards for each descriptor 
are arranged in ascending sequence on accession number. 

A possible list representation for this type of index 
appears in Figure 2.47B. The list contains an arbitrary num- 
ber of sublists, each of which is associated with a separate 
descriptor. The value pointer for the first component in a 
sublist specifies the descriptor for that sublist. The value 
pointer for each of the remaining components in a sublist 
specifies a card that contains the descriptor for the sublist. 


INDEX_LIST: | | 


Eee eee kos ie 


Eee 


PO Ba 
is 


RES 


To simplify the organization of the program that creates 
the index list and prints it, a main procedure (INDEX) is 
designed to operate with two function procedures (GET _ 
DESCRIPTOR and GET DESCRIPTOR COMPONENT) 
and two subroutine procedures (INSERT CARD and 
PRINT INDEX): 

1. GET_DESCRIPTOR obtains the next descriptor in a 

catalog card. 

2. GET_ DESCRIPTOR COMPONENT obtains the 
address of the first component in a sublist that is associated 
with a specified descriptor. When no sublist exists for the 
descriptor, a sublist is created, and the address of its first 
component is returned. 

3. INSERT CARD inserts a catalog card in a specified 
sublist. 3 

4. PRINT INDEX prints the index list in sort order. 


sea 


ee TO ea CRIN 


ey 


Risk 
ey WN 


Key: 


Di specifies the descriptor for the ith sublist. 


Cij specifies the jth catalog card in the ith sublist. 


Figure 2.47B. Representing an index with a list of lists 
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Figure 2.47C contains the GET_DESCRIPTOR function 
procedure. It uses one parameter (DESCRIPTOR 
_ STRING), which is a varying-length character string that 
has a maximum length of 71 characters. The value of the 
parameter initially consists of the characters in columns 11 
through 80 of a catalog card and an additional blank char- 
acter appended on the right. 


) 

GET_DESCRIPTOR: 

PROCEDURE (DESCRIPTCR_STRING) 

RETURNS (CHARACTER (106))93 
DECLARE 

DESCRIPTOR_STRING CRKARACTER(7)) 

VARYING, 

DESCRIPTOR CHARACTER(10), 

(C1,C2) FIXED DECIMAL (2); 
FIRST_CHARACTER: 


DO 

Cl = 1 TO LENGTH(DESCRIPTCR_ST2IN35); 

IF 

SUBSTR(DESCRIPTOR_STRING, Cleidaw=* ° 

THEN | 
GO TO 
LAST_CHARACTER; 
ENO; 


RETURN_BLANK_DESCRIPTOR: 
RETURN((1O)® *)5 
LAST_CHARACTER: 


DO 
C2 = Cl TO LENGTH 
(DESCRIPTOR_STRING); | 

IF | 

SUBSTR(DESCRIPTOR_STRING,C2,1) = * * 

THEN | 

GO TQ 
EXTRACT _DESCRIPTOR: 
END; 


EXTRACT _DESCRIPTOR: 
DESCRIPTOR = SUBSTR 
(DESCREPTOR_STRING,C1,CZ-1} 
SHIFT_DESCRIPTOR_STRING: 
DESCRIPTOR_STRING = 
SUBSTR(DESCRIPTOR_STRING, C213 
RETURN_ DESCRIPTOR: 
RETURN(DESCRIPTOR) ; 
END 
GET_DESCRIPTOR; 


Figure 2.47C. The GET DESCRIPTOR function 


Each invocation of GET DESCRIPTOR obtains the 
first descriptor in parameter DESCRIPTOR_ STRING and 
returns it to the point of invocation. The first descriptor is 
also deleted from DESCRIPTOR_ STRING, and if the 
descriptor contains more than ten characters, the leftmost 
ten are returned. When no descriptors remain in 
DESCRIPTOR_ STRING, an invocation of GET __ 
DESCRIPTOR produces a string of ten blank characters. 

The function procedure GET_DESCRIPTOR _ 
COMPONENT appears in Figure 2.47D. The function uses 
two parameters: DESCRIPTOR, which specifies a descrip- 
tor word, and INDEX LIST, which is the pointer head of a 


list of lists that has the organization shown in Figure 2.47B. 


AZ 


GET_DESCRIPTOR_COMPONENT = 
7 PROCEDURE (DESCRIPTOR.» INDEX_LIST) 
RETURNS (POINTER); 
DECLARE 
N FIXED DECIMAL(5), 
DESCRIPTOR CHARACTER(10), 
DESCRIPTOR_IMAGE BASED 
(DESCRIPTOR_ADDRESS) CHARACTER(10), 
(INDEX_LIST, SUBLIST) POINTER, 
DATA_AREA AREA EXTERNAL; 
N= 15 
SUBLIST = INDEX_LIST; 
TEST_DESCRIPTOR: 


IF 
SUBLIST = NULL 
THEN 
GO TO 
INSERT_DESCRIPTORS 
DESCRIPTOR_ADDRESS = GET_VALUE 
(GET_VALUE(SUBLIST)); 

IF 
DESCRIPTOR_ADDRESS->DESCRIPTOR_IMAGE 
<DESCRIPTOR 

THEN 
DO; 
N=N + 13 
SUBLIST = GET_LINK(SUBLIST)3; 
GO TO 
TEST_DESCRIPTOR; 
END; 

IF 
DESCRIPTOR_ADORESS->DESCRIPTOR_ IMAGE 
= DESCRIPTOR 

THEN 


RETURN(GET_VALUE(SUBLIST))35 
INSERT_DESCRIPTOR: 
ALLOCATE DESCRIPTOR_IMAGE IN 
(DATA_LAREA) SET(DESCRIPTOR_ADDRESS) 3; 
DESCRIPTOR_ADORESS-—>DESCRIPTOR_IMAGE 
= DESCRIPTOR; 
CALL INSERT_NVTCINDEX_LIST Ny, 
FORM_BODY (DESCRIPTOR —ADDRESS»"D*, 
NULL)» *L*)5 
RETURN(GET_VALUE(ADDRESS_NVT 
(CINDEX_LIST»N)D))35 
END . 
GET_DESCRIPTOR_COMPONENT $ 


Figure 2.47D. The GET _ DESCRIPTOR COMPONENT function 


GET DESCRIPTOR COMPONENT searches INDEX _ 
LIST for a sublist whose first component specifies the same 
descriptor as parameter DESCRIPTOR. When the sublist is 
found , the address of its first component is returned. If no 
sublist exists for the descriptor, the function creates a sub- 
list and inserts it into INDEX_ LIST in ascending sequence 
on the descriptor. The function then returns the address of 
the first component in this new sublist. 

Note that DESCRIPTOR is a ten-position character 
string whose descriptor value is adjusted to the left and 
extended, if necessary, with blanks on the right. 

Figure 2.47E contains the subroutine procedure 
INSERT CARD. The subroutine uses two parameters: 
CATALOG CARD ADDRESS, which represents the 


storage address of a catalog card, and DESCRIPTOR_LIST, 
which specifies the address of the first list component in a 
sublist within the index list UNDEX_ LIST). 


INSERT_CARD: 
PROCEDURE (CATALOG_CARD_ADDRESS, 
DESCRIPTOR_LIST); 

DECLARE 
N FIXED DECIMAL(5), 
CATALOG_CARD_ADDRESS 
POINTER, 
DESCRIPTOR_LIST POINTER, 
CARD_COMPONENT POINTER, 
1 CARD_IMAGE BASEDCIMAGE_ADDR), 
2 ACCESSION#_IMAGE CHARACTER(10), 
2 DESCRIPTOR_GROUP_ IMAGE 
CHARACTER(70)3 

INITIALIZE: ! 
N= 13 
CARD_COMPONENT = 
DESCRIPTOR_LISTS$ 

NEXT_CARD: 
N=N #4 135 
CARD_COMPONENT = GET_LINK 
(CARD_COMPONENT) 3 


IF 
CARO_COMPONENT = NULL 
THEN 
GO TO 
INSERT 3$ 
IMAGE_ADOR = GET_VALUE 
(CARD_COMPONENT) $ 
IF 
(IMAGE_ADOR->ACCESSION#_IMAGE 
< CATALOG_CARD_ADDRESS-> 
ACCESSION#_ IMAGE) 
THEN 
GO TO 
NEXT_CARD; 
IF 
( IMAGE_ADDR->ACCESSION#_ IMAGE 
= CATALOG_CARD_ADDRESS-> 
ACCESSION#_ IMAGE) 
THEN 
RETURNS; 
INSERT: 


CALL INSERT_NVT(DESCRIPTOR_LIST, 
NyCATALOG_CARD_ADDRESS» "0° )3 
RETURNS; 


END 
INSERT_CARD3$ 


Figure 2.47E, The INSERT _CARD subroutine 


INSERT CARD creates a new list component for the 
catalog card and inserts the component into the specified 
-sublist. Insertion occurs in ascending sequence on accession 


number. | 
When all catalog cards have been inserted into the index 


list, the list is printed by the subroutine PRINT INDEX 
given in Figure 2.47F. The subroutine uses the name of the 
index list INDEX LIST) as its only parameter and prints 
the list on the standard system-output file, SYSPRINT. 


PRINT_INDEX: 
PROCEDURE (INDEX_LIST);3 
DECLARE 
(INDEX_LIST,»SUBLIST) POINTER, 
POINTER POINTER, 
DESCRIPTOR BASED(DESCRIPTOR_AOODORESS) 
CHARACTER(10), 
1 CARD_IMAGE BASED(CARD_ADDRESS), 
2 ACCESSION#_ IMAGE CHARACTER(10), 
2 DESCRIPTOR_GROUP_ IMAGE 
CHARACTER(70)3 
SUBLIST = INDEX_LISTs 
PUT PAGE LIST(*OUTPUT FROM PRINT_INOEX 
PUT SKIP(2);5 
GET_SUBLIST: 
DO 
WHILE (SUBLIST+=NULL)$ 
DESCRIPTOR_ADDRESS = GET_VALUE 
(GET_VALUE(SUBLIST))3 
PRINT_OESCRIPTOR: 
PUT 
EOI T(DESCRIPTOR_ADDRESS—->DESCRIPTOR) 
(A); 
PUT 
SKIP; 
POINTER = GET_LINK 
(GET_VALUE(SUBLIST))3 
PRINT_CARDS: 


DO 
WHILE(POINTER -~= NULL)3 
CARD_ADDRESS = GET_VALUECPOINTER) $ 
PUT 
EDIT (CARD_ADDRESS~>CARD_ IMAGE) 
(A)s$ 
PUT 
SKIP; 
POINTER = GET_LINK( POINTER); 
ENO_PRINT_CARDS: 
END; 
PUT 
SKIP(2)5 


SUBLIST = GET_LINK(SUBLIST)$ 
END_GET_SUBLIST: 
END; 
END 

PRINT_INDEX; 


Figure 2.47F. The PRINT INDEX subroutine 


Construction and printing of the index list is controlled 
by the procedure INDEX, which appears in Figure 2.47G. 
INDEX reads an arbitrary number of catalog cards from the 
standard system-input file, SYSIN, and allocates storage for 
each card in the storage area called DATA AREA. If the 
number of cards exceeds the storage capacity of DATA _ 
AREA, a message is printed to indicate insufficient storage. 
Reading then ceases, and only those cards allocated in 
DATA_ AREA are indexed. 

As each card is read, its descriptors are scanned, and the 
address of the card is inserted into the proper sublist for 
each descriptor within the index list. When all cards have 
been processed in this manner, the index list is printed, as 
shown in Figure 2.47H. 
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INDEX: 
PROCEDURE $ 

DECLARE 
1 CATALOG_CARD, | 
2 ACCESSION# CHARACTER(10), 
2 DESCRIPTOR _GROUP CHARACTER(70), 
1 CARD_IMAGE BASED 
(IMAGE_ADORESS), © 


2 ACCESSION#_IMAGE CHARACTER(10), OUTPUT FROM PRINT_INDEX: 

2 DESCRIPTOR_GROUP_IMAGE 

CHARACTER(70), BLACK ITE SMALL 
DESCRIPTOR CHARACTER(10), AQ-1L7-RZ PAINTING BLACK WHITE 
DESCRIPTOR STRING CHARACTER(71) T2-XY4-16 PHOTOGRAPH BLACK WHITE LARGE 
VARYING, _ | Y9-016-X8 SCULPTURE MARBLE BLACK SMALL 


LIST_AREA AREA, 

DATA_AREA AREA, | eer 

paiiet BYE eatin T2-XY4-16 PHOTOGRAPH BLACK WHITE LARGE 
INDEX_LIST, AVAIL = NULL; | 

ON ENDFILE (SYSIN) GO TO PRINT; 


° MARBLE 
Oia lice Y8-123-X7 SCULPTURE MARBLE WHITE MEDIUM 
LISTC* INSUFFICIENT STORAGE FOR Y9-016-X8 SCULPTURE MARBLE BLACK SMALL 


COMPLETE INDEX®*)3 
GO TO PRINTs END; 


MEOIUM 

CALL AREA_OPEN(LIST_AREAsAVAIL) 
PUT PAGE LIST(*INPUT TO INDEX:")3 ¥8-123-X7 SCULPTURE MARBLE WHITE MEDIUM 
PUT SKIP; 

ET_CARD: 

GET_ ae PAINTING ern 
EDIT (CATALOG_CARD) (A(10),A(70)) AQ-1L7-RZ PAINTING BLACK WHITE 
PUT SKIP EDIT(CATALOG. CARD)(A): 
ALLOCATE CARD_IMAGE IN(DATA_AREA) SEE RARA 


SET( IMAGE_ADDRESS); 
 IMAGE_ADDRESS->CARD_IMAGE = 
CATALOG_CARD; 
DESCRIPTOR_STRING = 
| DESCRIPTOR_GROUPI|* *; 
NEXT_DESCRIPTOR: | 
DESCRIPTOR = GET_DESCRIPTOR 
(DESCRIPTOR_STRING) ; 
IF OESCRIPTOR = (10)" * 
THEN GO TO GET_CARD; 
CALL INSERT_CARD( IMAGE_ADDRESS, 
GET_DESCRIPTOR_COMPONENT 
(DESCRIPTOR, INDEX_LIST))3 
GO TO | 
NEXT_DESCRIPTOR; 


T2-XY4-16 PHOTOGRAPH BLACK WHITE LARGE 


SCULPTURE 
Y8-123-X7 SCULPTURE MARBLE WHITE MEDIUM 
Y9-016-X8 SCULPTURE MARBLE BLACK SMALL 


SMALL 
AQ-1L7-RZ PAINTING BLACK WHITE SMALL 
Y9-016-X8 SCULPTURE MARBLE BLACK SMALL 


WHITE 
A9-1L7-RZ PAINTING BLACK WHITE SMALL 


PRINT: 
T2-XY4-16 PHOTOGRAPH BLACK WHITE LARGE 
Soe een NOE RT NUES CIM) Y8-123-X7 SCULPTURE MARBLE WHITE MEDIUM 
END INDEX: 
Figure 2.47G, The INDEX procedure igure 2.47H. Printout from PRINT_INDEX 
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REVIEW OF LISTS OF LISTS 


This chapter shows how to extend the flexibility of a 
pointer list so that it can be used to link other lists as well 

as data items (see Figure 2.48). The resulting list of lists 
uses a type code within each list component to distinguish 


LIST_AREA 


[oN] belo N Hto NN etoN | 


AVAIL: 


between sublists and data items. With this code, sublists can 
in turn contain other sublists to an arbitrary depth. Asa 
result, new lists can be generated as the need arises during 
the course of program execution, and the programmer is 
freed from having to know the exact number of lists a pro- 
gram will require. 


oN bpN | 


DNLEPN_ BN BEN bPN_PENN 
un BL LEeL LPL 


DATA_AREA 


‘igure 2.48. List of lists 


SUMMARY 


1. A list of lists is a more general type of pointer list. 

2. Besides permitting element items, arrays, and struc- 
tures to be members of a list, a list of lists also permits a list 
itself to be a member of another list. 

3. A list of lists provides the same advantages as pointer 
lists: avoiding data duplication and reducing data move- 
ment. 

4. Alist of lists removes the need to know the exact 
number of lists a program will require during execution. As 
the need arises during program execution, a new list can be 
generated automatically and inserted into a master list of 
lists. : 





jo} Td Pee 


5. A type code within each list component determines 
whether the component specifies the address of a data item 
or the address of a sublist. 

6. The subroutines and functions developed in this 
chapter for processing lists of lists fall into four categories: 

a. Creating a list of available storage components 

b. Manipulating component elements in a list of lists 

c. Manipulating the top level of a list of lists 

d. Manipulating all levels of a list of lists 


Elementary procedures are developed first and used in turn 
to create higher-level procedures. 
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